Troubleshooting

Start with status:

npx -y @tagpilot/ga4-mcp status

It lists the Google sign-ins saved on this computer and whether each is still valid. It says the API key isn't set: that's normal, because your AI client passes the key to the server. Put TAGPILOT_API_KEY=tpk_your_key in front to check one key. The server's own log goes to stderr (stdout is the MCP channel): in Claude Code, check /mcp or start claude --debug; other clients have an MCP log view.

API key

"TAGPILOT_API_KEY is not set" The server started without the key. Add TAGPILOT_API_KEY to the server's env in your AI client's config (see Getting Started), then restart or reconnect the server. When you run login in a terminal, put the key in front of the command: TAGPILOT_API_KEY=tpk_your_key npx -y @tagpilot/ga4-mcp login.

"Tag Pilot rejected TAGPILOT_API_KEY (invalid or revoked)" (HTTP 401) The key is mistyped, incomplete or revoked. Create a new key on the GA4 MCP page and update your config.

"TAGPILOT_API_KEY does not have the ga4:mcp scope" (HTTP 403) The key was made elsewhere in the app, for example a Lead Tracking key under Settings → API keys. Those keys have other permissions. Create a key on the GA4 MCP page instead.

Google sign-in

"Waiting for you to sign in with Google" Finish the sign-in in the browser window that opened, then ask again. No window? Open the link from the message. The link is valid for 10 minutes; after that, ask again to get a new one.

The AI client times out during the first sign-in A tool call waits 45 seconds for the browser sign-in, then answers "Waiting for you to sign in" so the client doesn't give up. The sign-in keeps waiting in the background. Finish it in the browser and repeat the question. If your client still times out, lower GA4_MCP_AUTH_WAIT_SECONDS, or sign in from a terminal first with login:

TAGPILOT_API_KEY=tpk_your_key npx -y @tagpilot/ga4-mcp login

"Google hasn't verified this app" Google is still reviewing Tag Pilot's app. Click Advanced, then Go to … (unsafe), to reach the consent screen.

"Google sign-in was not completed (access_denied)" You cancelled the consent screen or didn't approve the permission. Ask again and approve See and download your Google Analytics data.

"Sign-in link mismatch" The browser tab belonged to an older sign-in attempt. Close it and use the link from the latest message.

"Your Google sign-in for GA4 expired or was revoked" (Google invalid_grant) Google no longer accepts the saved token, so it was deleted. Ask again and sign in again. Google expires tokens after 6 months without use, when you remove the app's access in your Google account, and in some cases when you change your password.

Signing in on a remote machine

If the AI client runs on a server, in a container or over SSH, the browser can't reach the sign-in callback on that machine. Use a fixed port and forward it.

Connect to the server with the port forwarded:
```
ssh -L 53682:127.0.0.1:53682 you@server
```

On the server, sign in from the terminal:

TAGPILOT_API_KEY=tpk_your_key GA4_MCP_OAUTH_PORT=53682 GA4_MCP_NO_BROWSER=1 npx -y @tagpilot/ga4-mcp login

Open the printed link in the browser on your own computer and approve. Google sends you back to 127.0.0.1:53682, which the tunnel forwards to the server.

The token is saved on the server, and the MCP server there uses it as long as it runs with the same key. To sign in from the AI client instead, put GA4_MCP_OAUTH_PORT and GA4_MCP_NO_BROWSER in the server's env.

Tag Pilot API errors

Message	Meaning	What to do
"Tag Pilot rate limit reached" (429)	More than 60 sign-in or token requests a minute for one key	Wait for the time in the message
"Tag Pilot could not reach Google to exchange the sign-in token" (502)	Google's token service didn't answer	Usually temporary; try again shortly
"Google sign-in for the GA4 MCP is not available" (503)	Sign-in is switched off on Tag Pilot's side	Try again later; contact us if it persists
"Could not reach Tag Pilot"	No connection to `api.tagpilot.io`	Check your internet connection, proxy or firewall

Only sign-in and token refreshes go through Tag Pilot (about once an hour while you use it). Reports keep working as long as the current access token is valid.

Google Analytics errors

"The signed-in Google account has no access to property …" That Google account needs at least the Viewer role on the GA4 property. Ask "Which GA4 properties do I have?" to see what it can read. Signed in with the wrong account? Run npx -y @tagpilot/ga4-mcp logout and ask again.

"… is not a GA4 property ID" / "Not found" Use the numeric property ID (e.g. 123456789), not the measurement ID (G-XXXXXXX). Universal Analytics properties (UA-…) aren't supported.

"GA4 rejected the request" A dimension or metric name is wrong, or the two can't be combined (for example some item-scoped and session-scoped fields). Custom fields need their API name, such as customEvent:payment_type; ask the AI client to look them up with get_custom_dimensions_and_metrics.

"GA4 quota exhausted" (429) GA4 Data API quotas are per property and refill hourly and daily. They're shared with other tools reading the same property (Looker Studio, other apps). Wait a few minutes, or make requests cheaper: shorter date ranges, fewer dimensions, lower row limits. Ask for return_property_quota: true to see what's left. Limits are in Google's quota documentation.

"Google Analytics API error (HTTP 5xx)" A problem on Google's side; retry shortly. Funnel reports use Google's alpha funnel API, which fails more often than other reports.

Numbers differ from the GA4 interface

The tools return what Google's Data API returns, with notes when it adjusts the data:

Thresholding: with Google signals or demographics, GA4 can hide rows with few users, so totals can be lower. Removing demographic dimensions or widening the date range helps.
Sampling: the result says how many events it was based on.
(other) rows: with many distinct values, GA4 groups the rest into (other). Narrow the date range or add filters.
Different settings: check the date range, the time zone (reports use the property's), the attribution scope (session vs first-user dimensions) and whether the GA4 report has filters or comparisons applied.
Recent data: the last 24–48 hours can still change while GA4 processes them.

MCP client issues

The tools don't show up Restart the AI client after changing its config, and check the server's log. Make sure Node.js 18 or newer is installed: node --version.

"npx: command not found" or "spawn npx ENOENT" Desktop apps don't always see the PATH from your shell (common with nvm or Homebrew). Use the full path to npx as the command, from which npx (macOS, Linux) or where npx (Windows).

Still stuck? Contact us through the Tag Pilot app and include the status output (it shows only the first characters of your key).