Graphcms Troubleshooting: Common Issues and Fixes | OpsBlu Docs

Graphcms Troubleshooting: Common Issues and Fixes

Debug analytics issues on Hygraph (formerly GraphCMS) — GraphQL query gaps, frontend framework integration, preview mode conflicts, and webhook rebuild...

Hygraph (formerly GraphCMS) is a headless CMS with a GraphQL-native API. Like other headless CMS platforms, Hygraph never renders HTML — your frontend framework does. Analytics issues always trace back to how your frontend (Next.js, Gatsby, Nuxt, Remix, Astro, etc.) fetches data from the Hygraph GraphQL API and renders tracking code.

Hygraph-Specific Debugging Approach

Since Hygraph is API-only, debugging analytics requires checking two layers: the GraphQL API responses and your frontend's rendering pipeline.

Verify GraphQL API Delivers Analytics Config

# Test your Hygraph API endpoint for analytics-related fields
curl -s -X POST "https://api-[region].hygraph.com/v2/[project-id]/master" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"query":"{ siteSettings(where: {slug: \"global\"}) { trackingId gtmContainerId customHeadScripts } }"}' \
  | python3 -m json.tool

// In browser console, check what data reached the frontend
console.log('Hygraph data:', window.__NEXT_DATA__?.props?.pageProps || 'not found');

// Check if analytics scripts loaded
document.querySelectorAll('script[src*="gtag"], script[src*="gtm"]').forEach(s => {
  console.log('Analytics:', s.src);
});

Check Content API Stages

Hygraph has content stages (DRAFT, PUBLISHED). Your production site should fetch from PUBLISHED, but this is a common source of missing data:

# Explicitly request PUBLISHED stage
curl -s -X POST "https://api-[region].hygraph.com/v2/[project-id]/master" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ siteSettings(where: {slug: \"global\"}, stage: PUBLISHED) { trackingId } }"}'

Most Common Hygraph Analytics Issues

1. GraphQL Query Missing Analytics Fields

Symptoms: Page content renders fine but no analytics code appears. Other Hygraph data loads correctly.

Root cause: Your GraphQL query does not include the fields containing analytics configuration. GraphQL only returns explicitly requested fields.

Fix: Add analytics fields to your query:

query GetPageWithAnalytics($slug: String!) {
  page(where: { slug: $slug }) {
    title
    content {
      html
    }
  }
  siteSettings(where: { slug: "global" }) {
    trackingId
    gtmContainerId
    customHeadScripts
  }
}

2. Content Stage Mismatch (DRAFT vs PUBLISHED)

Symptoms: Analytics config visible in the Hygraph dashboard but missing on the production site. Works in preview mode.

Root cause: Your production frontend fetches from the DRAFT stage (or no stage specified, defaulting to DRAFT in some SDKs), but the analytics configuration was only published.

Fix: Ensure your production API calls explicitly request the PUBLISHED stage:

// When using @hygraph/management-sdk or fetch
const endpoint = 'https://api-[region].hygraph.com/v2/[project-id]/master';

// For production: use the published content API endpoint
// NOT the draft endpoint
const response = await fetch(endpoint, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    query: `{ siteSettings(where: {slug: "global"}, stage: PUBLISHED) { trackingId } }`
  })
});

3. Preview Mode Firing Production Analytics

Symptoms: Pageview spikes during content editing. Preview URLs appear in GA reports.

Root cause: Hygraph's preview integration loads your frontend with draft content, but analytics still fires against the production property.

Fix:

// Detect Hygraph preview mode
const isPreview = new URLSearchParams(window.location.search).has('preview') ||
  document.cookie.includes('__prerender_bypass') ||
  document.cookie.includes('__next_preview_data');

if (isPreview) {
  window['ga-disable-G-XXXXXXX'] = true;
}

4. Rich Text Renderer Stripping Script Tags

Symptoms: You embedded analytics code in a Hygraph Rich Text field but it does not render on the frontend.

Root cause: Hygraph's Rich Text field stores structured JSON. Most Rich Text renderers (@graphcms/rich-text-react-renderer and similar) deliberately strip <script> tags for security.

Fix: Do not store analytics code in Rich Text fields. Use a dedicated singleton model with a plain text or code field:

// In your Hygraph schema, create a "SiteSettings" model with:
// - trackingId (Single Line Text)
// - customHeadScript (Multi Line Text / Code field)

// Then render it in your layout, NOT through the Rich Text renderer:
<script dangerouslySetInnerHTML={{ __html: siteSettings.customHeadScript }} />

5. Webhook-Triggered Rebuild Delays

Symptoms: Analytics configuration updated in Hygraph but the live site shows old values for minutes.

Root cause: Static site generators rebuild on Hygraph webhooks, but the build + deploy pipeline takes time.

Fix: Use ISR or on-demand revalidation:

// Next.js API route for Hygraph webhook
export default async function handler(req, res) {
  const { operation, data } = req.body;
  if (data?.__typename === 'SiteSettings') {
    await res.revalidate('/');
    return res.json({ revalidated: true });
  }
  return res.json({ revalidated: false });
}

Environment Considerations

  • Hygraph is SaaS: No server to manage. All caching and CDN issues are on your frontend hosting side
  • API regions: Hygraph projects are hosted in specific regions (EU, US). Ensure your build server has fast access to the correct region
  • Asset CDN: Hygraph serves assets through its own CDN. Large images can affect LCP and overall page performance
  • Content localization: Hygraph supports localized fields. Ensure analytics configuration is in non-localized fields to avoid per-locale tracking gaps
  • Rate limits: Hygraph API has rate limits per plan. Build-time fetches for large sites may hit limits, causing missing data

Performance Issues

Tracking Issues

  • Events Not Firing - Debug GraphQL query gaps, content stage mismatches, and preview mode leakage
Back to top