Fix Common GA4 Data API & IAM Errors
When connecting an AI agent or querying the Google Analytics 4 Data API, five common errors cause over 90% of failures. This guide covers the root cause and immediate resolution for each error.
1. Error 403: The Caller Does Not Have Permission
The Symptom
google.api_core.exceptions.PermissionDenied: 403 The caller does not have permission
User does not have sufficient permissions for this property.The Root Cause
The Google Cloud Service Account authenticated successfully, but it has not been granted access inside Google Analytics. Creating a service account in Google Cloud Console does not grant it access to your analytics data. You must add the service account email as a Viewer inside the Google Analytics Admin interface.
The Nine-Step Resolution
- Open your service account JSON key file in any text editor.
- Copy the
client_emailvalue (format:your-agent@your-project.iam.gserviceaccount.com). - Open Google Analytics.
- Select the property whose ID matches your
GA4_PROPERTY_ID. - Click the gear icon (Admin) in the bottom-left corner.
- In the Property column, click Property access management.
- Click the blue + button in the top-right corner, then click Add users.
- Paste the
client_emailinto the email field and uncheck Notify new users by email. - Under Direct roles, select Viewer (read-only) and click Add.
Access takes effect immediately with zero propagation delay. For screenshots and detailed IAM guidance, see the Permissions Guide.
2. Error 400: Invalid Dimension or Metric Name
The Symptom
google.api_core.exceptions.InvalidArgument: 400 Field pageviews is not found.
Field conversions is not found in this property.The Root Cause
Your AI assistant requested a field name from Universal Analytics (sunset July 2023) or an older API schema. Common legacy terms like pageviews, uniquePageviews, ga:sessions, and conversions are rejected by the GA4 Data API.
Common Field Translations
| Invalid Legacy Name | Valid GA4 Data API Name | Type | Notes |
|---|---|---|---|
pageviews | screenPageViews | Metric | Total pages viewed across web and app |
uniquePageviews | screenPageViews | Metric | GA4 does not track unique views; use sessions per page |
conversions | keyEvents | Metric | Renamed by Google on May 6, 2024 |
users | totalUsers or activeUsers | Metric | activeUsers is GA4's primary user metric |
bounceRate | bounceRate | Metric | In GA4, bounceRate is the inverse of engagementRate |
avgSessionDuration | averageSessionDuration | Metric | Average duration in seconds |
sourceMedium | sessionSourceMedium | Dimension | Dimension combining source and medium |
channelGrouping | sessionDefaultChannelGroup | Dimension | Default channel group (Organic, Direct, Paid) |
landingPage | landingPage | Dimension | Landing page path without query strings |
pagePath | pagePath | Dimension | Page URL path |
This MCP server automatically checks names against your live schema before dispatching queries. If you run into an unknown field, ask your agent to call search_schema('<keyword>').
3. Property ID vs. Measurement ID Mismatch
The Symptom
google.api_core.exceptions.InvalidArgument: 400 Invalid property ID: "G-XXXXXXXXXX".
Property ID must be numeric.The Root Cause
You passed your web data stream Measurement ID (starting with G-) instead of your numeric Property ID.
- Measurement ID (
G-XXXXXXXXXX): Used by front-end tracking snippets (gtag.js, Google Tag Manager) to send events into GA4. - Property ID (
123456789): A 9-digit number used by the Google Analytics Data API and Admin API to query reports.
Where to Find the Numeric Property ID
- Open Google Analytics.
- Click Admin (gear icon at bottom left).
- Under the Property column, click Property details.
- The numeric Property ID appears in the top-right corner (e.g.
555043732).
Set this number as your environment variable:
export GA4_PROPERTY_ID="555043732"4. Error 429: Resource Exhausted / Quota Limits
The Symptom
google.api_core.exceptions.ResourceExhausted: 429 Exhausted property quota tokens.
Resource has been exhausted (e.g. check quota).The Root Cause
Google Analytics 4 enforces hourly and daily API token quotas per property:
- Standard Properties: 25,000 tokens per hour, 5,000 concurrent requests, and 10 dimensions per query.
- GA4 360 Properties: 250,000 tokens per hour.
Tokens are consumed based on query complexity (number of dimensions, date range length, and row count).
How to Prevent Quota Exhaustion
- Narrow Date Ranges: Query
last 30 daysinstead oflast 365 daysduring interactive exploration. - Limit Dimensions: Keep queries to 2–4 dimensions. Each additional dimension multiplies row combinations exponentially.
- Use Row Limits: Specify
limit: 50orlimit: 100rather than pulling thousands of rows into your client context window. - Use Built-in Row Guards: GA4 MCP includes pre-query row estimators that warn you before large multi-thousand-row requests execute.
5. Error 400: Incompatible Dimensions and Metrics
The Symptom
google.api_core.exceptions.InvalidArgument: 400 The request's dimensions and metrics are incompatible.The Root Cause
In GA4, data is organized across three primary scopes:
- User Scope: Attributes of the person (e.g.,
firstUserDefaultChannelGroup,firstUserSource). - Session Scope: Attributes of the visit (e.g.,
sessionDefaultChannelGroup,sessionSource,sessions). - Event Scope: Attributes of a specific action (e.g.,
eventName,pagePath,eventCount).
Mixing incompatible scopes (such as pairing user-scoped acquisition dimensions with hit-level event metrics) will cause the Google Analytics Data API to reject the request.
The Compatibility Rules
- Pair
session*dimensions (sessionDefaultChannelGroup,sessionSource) with session metrics (sessions,bounceRate,averageSessionDuration). - Pair
pagePathoreventNamewith event metrics (screenPageViews,eventCount,keyEvents). - Pair
firstUser*dimensions with user metrics (newUsers,activeUsers).
To view valid combinations, consult our Compatible Combinations Guide.
In-Session Setup Recovery
If your setup breaks mid-session due to a missing property ID, an expired token, or missing credentials, you do not need to restart your client or edit config files manually.
Ask your agent:
Run setup_ga4_access to reconnect my analytics credentials.The server will prompt you for the missing value, validate the connection against Google Cloud, and restore access immediately inside the active chat.
Next Steps
- Installation Guide: Set up your Google Cloud Service Account and local MCP server.
- Query Shapes: Learn valid filter syntax, regex rules, and ordering parameters.
- Skills Index: Browse 16 ready-to-use analytical playbooks with proven field combinations.