gh-henkisdabro-wookstar-claude-code-plugins-ga-suite/skills/ga4-custom-dimensions/references/dimension-troubleshooting.md

Custom Dimension Troubleshooting Guide

Quick Diagnosis Flowchart

Are custom dimensions appearing in reports?
│
├─ YES → Is data accurate?
│        ├─ YES → No action needed
│        └─ NO → Jump to "Inaccurate Data" section
│
└─ NO → Is it after 48 hours?
        ├─ NO → Wait, normal processing delay (24-48 hours)
        └─ YES → Start troubleshooting below

---

Most Common Issues & Solutions

Issue 1: Dimension Doesn't Appear After 48 Hours

Frequency: 95% of reported problems

Check 1: Verify Code Still Sends Parameter

Go to DebugView to see if current events include the parameter:

1. GA4 Admin → DebugView
2. Look at events fired in last 5 minutes
3. Find the event type (form_submit, page_view, etc.)
4. Click to expand event details
5. Look for parameter in list

Expected: Parameter appears with correct value

If Parameter Missing:

• Code may not be live (deployment issue)
• Event may not be triggering at expected action
• Parameter may have been removed from code
• Test the action manually to verify event fires

Solution:

// Verify code actively sending parameter
gtag('event', 'test_event', {
  'test_param': 'test_value'
});
// Check DebugView for this event

Check 2: Verify Case-Sensitive Parameter Name Match

GA4 is case-sensitive. The parameter name in code must match EXACTLY in registration.

DebugView shows: form_name Registered as: form_name ✓ CORRECT Registered as: Form_Name ✗ WRONG Registered as: formName ✗ WRONG

Solution:

1. Go to DebugView
2. Find event with parameter
3. Look at EXACT parameter name as shown
4. Copy that exact name
5. Compare to what you registered

If mismatch found:

• Delete incorrect dimension
• Create new dimension with correct parameter name
• Wait 24-48 hours

Check 3: Verify Scope is Correct

Wrong scope will cause dimension to not appear properly.

For event-scoped parameters:

• Parameter appears in gtag('event') call
• Each event can have different value
• Example: button_name varies by event

// If code looks like this → use EVENT scope
gtag('event', 'click', {
  'button_name': 'Subscribe'  // Different per event
});

For user-scoped parameters:

• Parameter appears in gtag('set') call
• Set once, applies to all events
• Example: subscription_tier remains same

// If code looks like this → use USER scope
gtag('set', {
  'subscription_tier': 'premium'  // Same for all events
});

For item-scoped parameters:

• Parameter in items array
• Goes inside each product object
• Example: item_color varies per product

// If code looks like this → use ITEM scope
gtag('event', 'purchase', {
  'items': [{
    'item_color': 'blue'  // Different per item
  }]
});

Solution:

• If scope wrong: Delete and recreate with correct scope
• Scope cannot be changed on existing dimension

Check 4: Verify Quota Not Exceeded

Standard GA4 property limits:

• Event-scoped dimensions: 50 maximum
• User-scoped dimensions: 25 maximum
• Item-scoped dimensions: 10 maximum

If at or over limit, GA4 silently fails to create dimension.

Solution:

1. Admin → Custom Definitions
2. Count existing dimensions by scope
3. If at limit: Delete unused dimensions
4. Then recreate the missing dimension

Example deletion process:

1. Find unused dimension in list
2. Click to select it
3. Click Delete
4. Confirm deletion
5. Wait 24 hours before creating replacement

Check 5: Verify Minimum Event Volume

Custom dimensions need sufficient event volume to populate in reports.

Minimum for visibility:

• At least 1,000 events with that parameter
• May not show if traffic very low

Solution:

• Check event volume in DebugView
• If traffic low, data will eventually populate
• Large websites: Usually visible within 48 hours
• Small websites: May take longer or be below threshold

For testing with low traffic:

• Use Realtime reports (shows faster)
• Check after several days of data collection
• Consider sampling: Manual filter to subset of users

Check 6: Verify Data Stream is Correct

Custom dimensions apply to their data stream. If created for wrong stream:

Problem: Created dimension for Data Stream A, but code sends to Data Stream B

Solution:

1. Verify Measurement ID in code

   gtag('config', 'G-XXXXXXXXXX');  // This is the data stream
   

2. Admin → Data Streams

3. Match Measurement ID to correct stream

4. Verify dimension created in THAT stream (not another)

5. If in wrong stream: Create in correct stream

---

Issue 2: Parameter in DebugView But Not in Reports

Timeline:

• Hour 0-6: Parameter fires in DebugView
• Hour 6-24: Should start appearing in reports
• Hour 24-48: Definitely should appear in reports

Within First 24 Hours: Normal

GA4 requires time to process events. This is expected behavior.

Solution: Wait until 48-hour mark, then check again.

After 48 Hours: Investigate

Use the diagnostic checklist above (Checks 1-6) to identify issue.

---

Issue 3: Dimension Values Inconsistent or Wrong

Problem: All Users Show Same Value

For event-scoped dimension:

• ✗ WRONG: All events showing "Button A" when multiple buttons exist
• Cause: Parameter only sent sometimes
• Solution: Verify code sends parameter for ALL instances

For user-scoped dimension:

• ✓ EXPECTED: All events from user showing "Premium" tier
• This is correct behavior for user scope

Problem: Null or Empty Values Appearing

Cause: Parameter sometimes not sent

Example:

gtag('event', 'form_submit', {
  'form_name': formElement.getAttribute('name')  // Could be null
});

If formElement doesn't exist or attribute missing → null value sent

Solution:

gtag('event', 'form_submit', {
  'form_name': formElement.getAttribute('name') || 'unknown_form'
});

Always provide default value.

Problem: Unexpected Values in Reports

Example: Report shows "button name: [object Object]" instead of actual name

Cause: Sending object or array instead of string

// WRONG - sending object
gtag('event', 'click', {
  'button_data': {name: 'Subscribe'}  // Object, not string!
});

// CORRECT - send string value
gtag('event', 'click', {
  'button_name': 'Subscribe'  // String value
});

Solution: Ensure values are primitive types (string, number, boolean)

---

Issue 4: Multiple Dimensions Created by Accident

Problem: Accidentally created "form_name", "form_Name", "formName" (all slightly different)

Solution:

1. Delete the incorrect/duplicate versions
2. Keep only the correct one
3. Wait 24-48 hours between deletions
4. Verify code sends correct parameter name

Deletion process:

1. Admin → Custom Definitions
2. Click each duplicate
3. Click Delete
4. Confirm
5. Wait 24 hours
6. Verify deletion complete

---

Issue 5: Dimension Quota Exceeded

Error: Cannot create new dimension, hitting quota limit

Standard GA4 Quotas:

• Event-scoped: 50 max (currently using X)
• User-scoped: 25 max (currently using X)
• Item-scoped: 10 max (currently using X)

Solution:

1. Admin → Custom Definitions
2. Identify unused dimensions
3. Delete low-priority dimensions
4. Now create new dimension

Prioritization for deletion:

• Delete: Dimensions with no data
• Delete: Dimensions not used in reports
• Delete: Experimental/testing dimensions
• Keep: Critical business metrics
• Keep: Frequently used dimensions

---

Dimension Data Quality Issues

Issue 6: High-Cardinality Dimensions (Too Many Values)

What is cardinality?

• Low: Few unique values (colors: red, blue, green)
• High: Many unique values (email addresses, IDs)

Problem: Creating dimension on high-cardinality parameter

Example:

gtag('event', 'form_submit', {
  'user_email': user.email  // MILLIONS of unique values
});

Impact:

• Report becomes unwieldy
• Performance impacts
• GA4 may limit display (shows "other" for rare values)

Solution: Use low-cardinality parameters

Good parameters (low cardinality):

• Button names: 5-10 values
• Form names: 3-8 values
• User tiers: 3-5 values
• Colors: 6-10 values
• Locations: 20-100 values

Bad parameters (high cardinality):

• Email addresses: Millions
• User IDs: Millions
• Timestamps: Continuous
• Session IDs: Unique per session
• Product SKUs: Often thousands+

Fix:

• Don't track high-cardinality data as custom dimension
• Use for analysis in DebugView only
• Or aggregate: Convert product_sku to product_category

Issue 7: Sending PII (Personally Identifiable Information)

Prohibited: Email, phone, SSN, credit card, name, IP address

// WRONG - Don't send PII
gtag('event', 'signup', {
  'user_email': 'john@example.com',  // PII!
  'user_name': 'John Doe'             // PII!
});

Solution: Use anonymous identifiers

// CORRECT - Use hashed or anonymous IDs
gtag('event', 'signup', {
  'user_tier': 'free',              // OK - non-PII attribute
  'signup_source': 'newsletter'      // OK - non-PII context
});

---

Debugging with DebugView

Enable DebugView (Three Methods)

Method 1: Chrome Extension (Easiest)

1. Install "Google Analytics Debugger" from Chrome Web Store
2. Click extension icon → Enable
3. Refresh website
4. Go to GA4 Admin → DebugView
5. Data appears immediately

Method 2: GTM Preview Mode

1. In GTM container → Click Preview
2. All GA4 tags automatically send debug_mode parameter
3. Go to GA4 DebugView
4. Data visible

Method 3: Manual Debug Code

gtag('config', 'G-XXXXXXXXXX', {
  'debug_mode': true
});

// Or per event
gtag('event', 'form_submit', {
  'form_name': 'Contact',
  'debug_mode': true
});

Using DebugView to Diagnose

Verification Checklist:

1. ✓ Event fires? See it in event stream
2. ✓ Parameter sends? See in event parameters
3. ✓ Parameter name correct? Check exact spelling/case
4. ✓ Parameter value correct? See actual value sent
5. ✓ Scope correct? User params in "User properties", item params in "Items"

DebugView Navigation:

• Left panel: Event stream (click to select)
• Right panel: Event details (expand sections)
• User properties section: Find user-scoped dimensions
• Items section: Find item-scoped dimensions

---

Testing Custom Dimensions

Manual Testing Workflow

1. Create test dimension

   • Name: "Test Dimension [your name]"
   • Register the test parameter

2. Add test code to page

   gtag('event', 'test_event', {
     'test_parameter': 'test_value_' + new Date().toLocaleTimeString()
   });
   

3. Verify in DebugView

   • Trigger event manually
   • See parameter in DebugView
   • Confirm parameter name matches registration

4. Wait 24-48 hours

5. Check test report

   • Analytics → Reports
   • Add test dimension
   • See test values appear

6. Delete test dimension

   • Once verified
   • Clean up test data

---

Getting Help & Debugging Checklist

Before Contacting Support

Use this checklist to diagnose issue:

• Parameter appears in DebugView?

  • YES: Parameter is being sent correctly
  • NO: Issue is in implementation, not GA4

• Parameter name matches registration (case-sensitive)?

  • YES: Continue
  • NO: Fix parameter name

• Scope selection correct (Event/User/Item)?

  • YES: Continue
  • NO: Delete and recreate with correct scope

• Under quota for scope type?

  • YES: Continue
  • NO: Delete unused dimensions

• 48 hours passed since registration?

  • YES: Continue
  • NO: Wait longer, processing is normal

• Sufficient event volume (1000+ events)?

  • YES: Continue
  • NO: May appear later as traffic increases

Debug Information to Gather

If contacting support, provide:

1. GA4 Property ID: properties/XXXXXXXXXX
2. Dimension name: Exactly as registered
3. Parameter name: Exactly as sent
4. Scope: Event/User/Item
5. Date created: When dimension registered
6. Event type: Which event sends parameter
7. DebugView screenshot: Showing parameter
8. Expected vs actual: What should appear vs what does

---

Prevention: Best Practices

Avoid Problems Before They Start

1. Plan before implementation

   • List all dimensions needed
   • Assign scopes to each
   • Check quota (don't exceed limits)
   • Get team approval

2. Use consistent naming

   • Standardize parameter names
   • Use snake_case
   • Clear, descriptive names
   • Document all parameters

3. Test with small rollout

   • Deploy to 1% of traffic first
   • Verify in DebugView
   • Wait 24-48 hours
   • Then full rollout

4. Version control parameters

   • If updating parameter name: Create new dimension
   • Don't modify existing dimensions
   • Keep version history

5. Monitor after creation

   • Check data appears after 48 hours
   • Verify data accuracy
   • Monitor for unexpected values
   • Set up alerts for anomalies

---

Quick Reference: Common Error Messages

Error	Cause	Solution
"Dimension not found"	Registered with wrong name	Create with correct name
"Parameter mismatch"	Case doesn't match	Verify exact case in DebugView
"Cannot create dimension"	Quota exceeded	Delete unused dimensions
"Dimension appears empty"	No data sent	Verify code sends parameter
"Shows '[object Object]'"	Sending object not string	Send string value only
"All values blank/null"	Parameter optional, sometimes missing	Add default value in code

---

Advanced: Debugging with GA4 DebugView API

For developers, use the Realtime Report API to programmatically verify:

from google.analytics.data_v1beta import BetaAnalyticsDataClient

client = BetaAnalyticsDataClient()

# Run realtime report to verify custom dimension
response = client.run_realtime_report(
    request={
        "property": "properties/PROPERTY_ID",
        "dimensions": [
            {"name": "customEvent:dimension_name"}
        ],
        "metrics": [
            {"name": "eventCount"}
        ]
    }
)

# Check if dimension appears with data
for row in response.rows:
    print(f"Dimension value: {row.dimension_values}")
    print(f"Event count: {row.metric_values}")

This confirms dimension is receiving data in real-time.