Netlify CMS / Decap CMS Troubleshooting Overview | OpsBlu Docs

Netlify CMS / Decap CMS Troubleshooting Overview

Common issues and solutions for static sites built with Netlify CMS and Decap CMS

Static sites built with Netlify CMS (now Decap CMS) have unique troubleshooting patterns. Since content is compiled at build time and served as static files, issues often relate to build processes, deployment pipelines, and client-side tracking implementation.

Common Issue Categories

Performance Issues

Static sites are inherently fast, but tracking scripts and third-party integrations can impact Core Web Vitals:

Tracking Issues

Analytics and marketing pixels require special handling on static sites:

  • Events Not Firing - Missing or broken tracking
  • Environment-specific problems - Preview vs production tracking
  • Build-time vs runtime data - Data layer configuration
  • SPA pageview tracking - Client-side routing issues

Build and Deployment Issues

Git-based workflow creates unique challenges:

  • Build failures - Template errors, plugin conflicts
  • Environment variables - Missing or incorrect configuration
  • Preview deploy tracking - Test data polluting production
  • Branch deploy configuration - Staging vs production setup

Static Site-Specific Challenges

Pre-Rendered Content

Unlike traditional CMSs, static sites generate HTML at build time:

Issue: Can't change tracking dynamically based on user Solution: Client-side JavaScript for user-specific tracking

Issue: Rebuilds required for tracking code changes Solution: Use GTM for tag management

Issue: Template errors break entire build Solution: Validate templates before committing

Git-Based Workflow

Every content change triggers a deployment:

Issue: High build frequency impacts performance Solution: Optimize build process, use incremental builds

Issue: Preview deploys create unique URLs Solution: Environment-specific tracking IDs

Issue: Editorial workflow creates branch deploys Solution: Conditional tracking based on environment

Client-Side Routing

Modern frameworks (Gatsby, Next.js) use SPA patterns:

Issue: Pageviews not tracked on route changes Solution: Route change listeners for virtual pageviews

Issue: Data layer not updating Solution: Push to data layer on route change

Issue: Tags fire multiple times Solution: Event deduplication logic

Build-Time Troubleshooting

Template Errors

Symptom: Build fails with template error

Common Causes:

  • Syntax errors in partials/includes
  • Missing environment variables
  • Undefined variables in templates
  • Plugin conflicts

Hugo example error:

Error: execute of template failed: template: partials/analytics.html:5:12:
executing "partials/analytics.html" at <.Params.author>: can't evaluate field Params in type string

Solution:

<!-- Before (causes error if .Params is undefined) -->
{{ .Params.author }}

<!-- After (safe check) -->
{{ with .Params.author }}{{ . }}{{ end }}

Environment Variable Issues

Symptom: Tracking IDs show as "undefined" or placeholder

Gatsby:

// Must prefix with GATSBY_
process.env.GATSBY_GA_ID  // ✓ Works
process.env.GA_ID          // ✗ Returns undefined

Next.js:

// Must prefix with NEXT_PUBLIC_
process.env.NEXT_PUBLIC_GA_ID  // ✓ Works
process.env.GA_ID              // ✗ Returns undefined

Hugo/Jekyll:

# Netlify.toml - context-specific environment
[context.production.environment]
  HUGO_GA_ID = "G-PRODUCTION"

[context.deploy-preview.environment]
  HUGO_GA_ID = "G-STAGING"

Plugin Conflicts

Symptom: Build fails after adding analytics plugin

Common Issues:

  • Multiple analytics plugins competing
  • Plugin version incompatibilities
  • Outdated dependencies

Solution:

# Clear cache and reinstall
rm -rf node_modules package-lock.json
npm install

# Update plugins
npm update gatsby-plugin-google-gtag

# Check for peer dependency warnings
npm list

Runtime Troubleshooting

Tracking Not Loading

Symptom: Analytics/pixels don't fire on deployed site

Checklist:

  1. Check environment - Are you excluding dev/preview?
  2. Verify script loads - Check Network tab for requests
  3. Check console errors - JavaScript errors blocking execution
  4. Test without ad blocker - Browser extensions blocking
  5. Verify tracking ID - Correct ID for environment

Preview Deploy Issues

Symptom: Preview deploys send data to production analytics

Solution:

// Environment detection
const hostname = window.location.hostname;
const isProduction = hostname === 'www.yoursite.com';
const isPreview = hostname.includes('deploy-preview');

const gaId = isPreview ? 'G-STAGING-ID' : 'G-PRODUCTION-ID';

Data Layer Not Populating

Symptom: GTM variables show as "undefined"

Checklist:

  1. Initialize before GTM - Data layer must exist first
  2. Check syntax - Valid JSON in data layer push
  3. Verify variable names - Match GTM variable configuration
  4. Check timing - Data layer pushed before tag fires
  5. Use GTM Preview - Debug data layer values

Framework-Specific Issues

Hugo Issues

Template lookup errors:

Error: template: _default/single.html:12:3: executing...

Solution: Check partial path exists: layouts/partials/analytics.html

Environment variable not found:

{{ getenv "HUGO_GA_ID" }}  // Returns empty string

Solution: Set in Netlify UI or netlify.toml

Jekyll Issues

Liquid syntax errors:

Liquid Exception: undefined method `first' for nil:NilClass

Solution: Add nil checks:

{% if page.categories %}
  {{ page.categories | first }}
{% endif %}

Environment not detected:

# _config.yml - jekyll.environment not set

Solution: Set in build command:

[build]
  command = "JEKYLL_ENV=production bundle exec jekyll build"

Gatsby Issues

Plugin not loading:

Error: Cannot find module 'gatsby-plugin-google-gtag'

Solution:

npm install gatsby-plugin-google-gtag
gatsby clean
gatsby build

Environment variables:

// Undefined at runtime
console.log(process.env.GATSBY_GA_ID);  // undefined in browser

Solution: Prefix with GATSBY_ and restart dev server

Next.js Issues

Script not loading:

// Script component not firing
<Script src="..." strategy="afterInteractive" />

Solution: Use id attribute:

<Script id="ga-script" strategy="afterInteractive" />

Router events:

// Events not tracked on route change
router.events.on('routeChangeComplete', handleRouteChange);

Solution: Add cleanup:

return () => {
  router.events.off('routeChangeComplete', handleRouteChange);
};

Debugging Tools

Browser DevTools

Console:

// Check tracking loaded
console.log(typeof gtag);  // Should be 'function'
console.log(typeof fbq);   // Should be 'function'

// Check data layer
console.log(window.dataLayer);

// Check GTM
console.log(google_tag_manager);

Network Tab:

  • Filter by "collect" or "analytics"
  • Verify requests sent
  • Check payload data
  • Look for 200 status codes

Tag Debugging Extensions

Google Analytics Debugger:

Meta Pixel Helper:

Tag Assistant:

GTM Preview Mode

  1. Open GTM container
  2. Click Preview
  3. Enter site URL (production or preview deploy)
  4. Debug panel opens
  5. See all tags, triggers, variables
  6. View data layer state

Netlify Deploy Logs

Check build logs for errors:

  1. Netlify Dashboard → Site → Deploys
  2. Click on deploy
  3. View deploy log
  4. Look for error messages
  5. Check build time (slow = potential issue)

Performance Monitoring

Core Web Vitals

Tools:

Key Metrics:

  • LCP < 2.5s (Good)
  • FID < 100ms (Good)
  • CLS < 0.1 (Good)

Tracking Impact

Measure impact of analytics/pixels:

Before adding tracking:

# Lighthouse CLI
lighthouse https://yoursite.com --view

After adding tracking:

lighthouse https://yoursite.com --view

Compare:

  • Performance score
  • LCP timing
  • Total Blocking Time
  • JavaScript execution time

Common Solutions

Reset Build Environment

# Clear Netlify cache
# In Netlify UI: Site Settings → Build & deploy → Clear cache

# Or add to netlify.toml
[build]
  command = "npm ci && npm run build"

Validate Configuration

// Add configuration logging
console.log('GA ID:', process.env.GATSBY_GA_ID);
console.log('Environment:', process.env.NODE_ENV);
console.log('Context:', process.env.CONTEXT);

Test Locally

# Hugo
hugo server --disableFastRender

# Jekyll
JEKYLL_ENV=production bundle exec jekyll serve

# Gatsby
gatsby clean && gatsby develop

# Next.js
npm run dev

Next Steps

Nach oben