Skip to main content
EmergentEMERGENT
Emergent SolutionsKnowledge Base

Server-Side Troubleshooting

Common issues, debugging techniques, and optimization strategies for server-side tagging implementations.

Debugging Tools

GTM Server Preview Mode

The most important debugging tool:

  1. In GTM Server Container, click Preview
  2. Open your website in a new tab
  3. View incoming requests and outgoing tags

Key Information Available

| Section | What to Check | |---------|---------------| | Requests | Incoming events from web container | | Tags | Which tags fired, status | | Variables | Resolved variable values | | Console | Error messages, warnings |

Cloud Logging

For production debugging:

# View recent logs
gcloud logging read "resource.type=cloud_run_revision AND resource.labels.service_name=gtm-server" --limit 50

# Filter for errors
gcloud logging read "resource.type=cloud_run_revision AND severity>=ERROR" --limit 20

# Real-time log streaming
gcloud logging tail "resource.type=cloud_run_revision"

Common Issues

Container Not Responding

Symptoms:

  • 502/503 errors
  • Requests timing out
  • Health check failures

Diagnosis:

# Check service status
gcloud run services describe gtm-server --region us-central1

# Check instance count
gcloud run services describe gtm-server --format="value(status.traffic)"

# View recent revisions
gcloud run revisions list --service gtm-server

Solutions:

| Cause | Solution | |-------|----------| | Container crashing | Check logs for startup errors | | Out of memory | Increase memory allocation | | Cold starts | Set minimum instances > 0 | | Config error | Verify CONTAINER_CONFIG value |

Events Not Arriving

Symptoms:

  • Server container receives no requests
  • Preview mode shows no activity

Checklist:

  • [ ] Web container has correct server URL
  • [ ] DNS resolves to correct endpoint
  • [ ] SSL certificate is valid
  • [ ] No firewall/WAF blocking requests
  • [ ] Consent mode not blocking

Debug Steps:

// Check in browser console
fetch('https://gtm.example.com/healthy')
  .then(r => r.text())
  .then(console.log);
// Should return "ok"

Tags Not Firing

Symptoms:

  • Events arrive but tags don't fire
  • Vendors not receiving data

Common Causes:

| Issue | Debug | Fix | |-------|-------|-----| | Trigger mismatch | Check trigger conditions | Update trigger | | Client not claiming | Check Client status | Configure Client | | Missing variables | Check variable values | Fix variable config | | API errors | Check Console tab | Fix API credentials |

GA4 Data Not Appearing

Diagnosis Checklist:

  1. Preview Mode: Does GA4 tag show as fired?
  2. DebugView: Do events appear in GA4 DebugView?
  3. Realtime: Check GA4 Realtime reports
  4. Network: Inspect outgoing request to GA4

Common Fixes:

// Verify Measurement ID format
// Correct: G-XXXXXXXXXX
// Wrong: UA-XXXXXXXX-X (this is Universal Analytics)

// Check data stream settings in GA4 Admin
// Data Stream → Web → Measurement ID

Cookie Issues

Symptoms:

  • Sessions splitting
  • Users not identified
  • Cross-domain not working

First-Party Cookie Debug:

// Check cookies in browser
document.cookie.split(';').filter(c => c.includes('_ga'));

// Verify cookie domain
// Should be: .example.com (with leading dot)
// Not: gtm.example.com (too specific)

Solutions:

| Issue | Solution | |-------|----------| | Wrong domain | Update cookie domain setting | | SameSite issues | Set SameSite=None; Secure | | Missing cookies | Check consent blocking | | Short expiry | Verify first-party setup |

Deduplication Failures

Symptoms:

  • Duplicate conversions in platforms
  • Event counts doubled

Fix:

Ensure event_id is:

  • Unique per event
  • Same in both client and server
  • Passed to all platforms
// Generate consistent event_id
const eventId = `${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;

// Use in data layer
dataLayer.push({
  event: 'purchase',
  event_id: eventId,
  // ...
});

// Also send to browser-side pixel with same ID
fbq('track', 'Purchase', {}, {eventID: eventId});

Performance Optimization

Latency Reduction

| Optimization | Expected Improvement | |--------------|---------------------| | Regional deployment | 20-50ms reduction | | Minimum instances | Eliminate cold starts | | Request batching | Fewer round trips | | CDN for static | Faster DNS resolution |

Deploy Closer to Users

# Multi-region deployment
gcloud run deploy gtm-server-us --region us-central1
gcloud run deploy gtm-server-eu --region europe-west1
gcloud run deploy gtm-server-asia --region asia-east1

# Use Cloud Load Balancer for routing

Container Configuration

# Optimized Cloud Run settings
resources:
  limits:
    cpu: '1'
    memory: '1Gi'
scaling:
  minInstanceCount: 2
  maxInstanceCount: 100
  concurrency: 80

Monitoring Setup

Key Metrics to Track

| Metric | Warning | Critical | Action | |--------|---------|----------|--------| | Request latency (p99) | > 500ms | > 2s | Scale up | | Error rate | > 1% | > 5% | Investigate | | Instance count | > 60% max | > 80% max | Increase max | | Memory usage | > 70% | > 90% | Increase memory |

Alerting Configuration

# Create alert for high error rate
gcloud alpha monitoring policies create \
  --display-name="GTM Server High Error Rate" \
  --condition-threshold-filter="resource.type=\"cloud_run_revision\" AND metric.type=\"run.googleapis.com/request_count\" AND metric.labels.response_code_class!=\"2xx\"" \
  --condition-threshold-value=5 \
  --condition-threshold-comparison=COMPARISON_GT

Custom Dashboard

Create a monitoring dashboard with:

  1. Request Volume - Total requests over time
  2. Latency Distribution - p50, p95, p99 latencies
  3. Error Rate - 4xx and 5xx responses
  4. Tag Performance - Individual tag success rates
  5. Instance Scaling - Active instances over time

Vendor-Specific Issues

Meta CAPI Errors

| Error | Cause | Solution | |-------|-------|----------| | Invalid access token | Token expired | Regenerate token | | Invalid pixel ID | Wrong format | Verify 15-16 digit ID | | Event rejected | Missing required params | Add action_source | | Low match rate | Poor user data | Hash correctly |

Google Ads Issues

| Error | Cause | Solution | |-------|-------|----------| | Conversion not tracking | Wrong conversion ID | Verify ID format | | Value missing | Variable not mapped | Check variable config | | Enhanced not working | Hashing issue | Verify SHA-256 format |

LinkedIn Issues

| Error | Cause | Solution | |-------|-------|----------| | 401 Unauthorized | Bad API token | Regenerate token | | Conversion not found | Invalid conversion ID | Verify in Campaign Manager |

Health Check Endpoint

The server container provides a health endpoint:

# Basic health check
curl https://gtm.example.com/healthy
# Returns: ok

# Detailed health (if configured)
curl https://gtm.example.com/healthz

Use this for:

  • Load balancer health checks
  • Uptime monitoring
  • Deployment verification

Recovery Procedures

Container Rollback

If a deployment causes issues:

# List revisions
gcloud run revisions list --service gtm-server

# Rollback to previous
gcloud run services update-traffic gtm-server \
  --to-revisions PREVIOUS_REVISION=100

Emergency Fallback

If server-side completely fails, temporarily revert web container:

  1. Remove Server Container URL from GA4 tag
  2. Re-enable direct vendor tags
  3. Debug and fix server-side issues
  4. Re-enable server-side routing

Previous: Marketing Pixels Related: Debug & Validation