Contentful Troubleshooting Overview | OpsBlu Docs

Contentful Troubleshooting Overview

Troubleshoot common issues with Contentful-powered sites including performance problems and tracking failures.

Common issues you may encounter with Contentful-powered websites and how to diagnose and fix them. Since Contentful is a headless CMS, most issues occur in your frontend framework implementation.

Performance Issues

Contentful sites built with modern frameworks (Next.js, Gatsby, Nuxt) can achieve excellent performance, but improper implementation can lead to slow loading times and poor Core Web Vitals.

Largest Contentful Paint (LCP)

LCP measures loading performance. Contentful-specific LCP issues include:

  • Unoptimized Contentful images - Large images from Contentful Image API
  • Slow API responses - Content Delivery API latency
  • Client-side rendering delays - Waiting for Contentful API on client
  • Large Rich Text fields - Heavy content processing
  • Missing image dimensions - Images from Contentful without width/height
  • Framework-specific issues - SSR hydration delays, CSR waterfalls

Target: LCP under 2.5 seconds

Cumulative Layout Shift (CLS)

CLS measures visual stability. Contentful-specific CLS issues include:

  • Images without dimensions - Contentful images loading without aspect ratio
  • Dynamic content loading - Content appearing after page load
  • Web fonts from Contentful - Custom fonts causing layout shifts
  • Rich Text rendering - Content reflow during processing
  • Embedded assets - Videos and media from Contentful shifting layout
  • Loading states - Skeleton screens that don't match final content

Target: CLS under 0.1

General Performance Best Practices

Content Delivery:

  • Use Contentful Image API with proper sizing parameters
  • Implement responsive images with srcset
  • Leverage Contentful CDN for global content delivery
  • Cache Contentful API responses appropriately

Framework Optimization:

  • Use Static Site Generation (SSG) when possible
  • Implement Incremental Static Regeneration (ISR) for Next.js
  • Preload critical Contentful assets
  • Optimize bundle size and code splitting

Image Handling:

  • Always specify image dimensions from Contentful
  • Use Contentful Image API transformations
  • Implement lazy loading for below-fold images
  • Use WebP format with Contentful Image API

Code Optimization:

  • Minimize Rich Text processing on client
  • Cache Contentful SDK instances
  • Debounce Contentful API calls
  • Use GraphQL instead of REST when possible

For general performance concepts, see the global performance hub.

Tracking & Analytics Issues

Events Not Firing

Common causes of tracking failures on Contentful sites:

  • Server-side rendering issues - Analytics not initialized on server
  • Client-side routing - Events not firing on navigation
  • Contentful Preview mode - Tracking in preview sessions
  • Data layer timing - Pushing data before GTM loads
  • JavaScript errors - Errors preventing analytics initialization
  • Missing dependencies - Analytics scripts not loaded
  • Environment configuration - Wrong IDs in different environments

Common scenarios:

  • GA4 events not firing on route changes (SPA issue)
  • Data layer undefined when pushing Contentful data
  • Duplicate events from multiple implementations
  • Preview content being tracked in production analytics

Tracking Best Practices

Framework Integration:

  • Initialize analytics in correct lifecycle (useEffect, componentDidMount)
  • Handle SSR vs CSR properly
  • Track route changes in SPAs
  • Exclude preview mode from tracking

Data Layer Management:

  • Initialize data layer before analytics scripts
  • Push Contentful data after content loads
  • Handle async Contentful API calls
  • Validate data before pushing

Testing:

  • Use separate analytics properties for development
  • Test in preview mode separately
  • Monitor console for JavaScript errors
  • Use browser extensions for debugging

Documentation:

  • Document all tracking implementations
  • Note Contentful content types tracked
  • Track schema changes in Contentful
  • Version control analytics code

For general tracking concepts, see the global troubleshooting hub.

Common Contentful-Specific Issues

Content Not Updating

Problem: Changes in Contentful not appearing on site.

Causes:

  • Cached content (CDN, browser, or application cache)
  • Using draft content in production
  • ISR/SSG not rebuilding
  • Wrong environment selected

Diagnosis:

  1. Check Contentful environment (master vs staging)
  2. Verify content is published, not draft
  3. Check build/deploy logs
  4. Clear all caches (CDN, application, browser)

Solutions:

Next.js ISR:

// pages/blog/[slug].tsx
export async function getStaticProps({ params }) {
  const post = await getContentfulPost(params.slug)

  return {
    props: { post },
    revalidate: 60, // Rebuild every 60 seconds
  }
}

Manual rebuild trigger:

  • Set up Contentful webhooks
  • Trigger rebuild on publish
  • Use on-demand ISR in Next.js

Clear Contentful CDN cache:

# Using Contentful CLI
contentful space environment clear-cache --environment-id master

Preview Mode Issues

Problem: Preview mode not working or tracking preview sessions.

Causes:

  • Preview API not configured
  • Missing preview access token
  • Analytics tracking preview mode
  • Client-side state not clearing

Solutions:

Next.js Preview Mode:

// pages/api/preview.ts
export default async function handler(req, res) {
  const { secret, slug } = req.query

  if (secret !== process.env.CONTENTFUL_PREVIEW_SECRET) {
    return res.status(401).json({ message: 'Invalid token' })
  }

  // Enable Preview Mode
  res.setPreviewData({})

  // Redirect to the path from the query
  res.redirect(slug ? `/${slug}` : '/')
}

// Disable preview
// pages/api/exit-preview.ts
export default async function handler(req, res) {
  res.clearPreviewData()
  res.redirect('/')
}

Exclude preview from analytics:

'use client'

export function Analytics() {
  const isPreview = usePreviewMode()

  if (isPreview) return null

  return <AnalyticsScript />
}

API Rate Limiting

Problem: Contentful API rate limit errors.

Causes:

  • Too many API requests
  • No caching implemented
  • Development mode hitting production API
  • Webhook loops

Diagnosis:

// Check rate limit headers
const response = await fetch(contentfulApiUrl)
console.log({
  limit: response.headers.get('X-Contentful-RateLimit-Limit'),
  remaining: response.headers.get('X-Contentful-RateLimit-Remaining'),
  reset: response.headers.get('X-Contentful-RateLimit-Reset'),
})

Solutions:

Implement caching:

// Cache Contentful responses
const cache = new Map()

async function getContentfulEntry(id: string) {
  if (cache.has(id)) {
    return cache.get(id)
  }

  const entry = await contentfulClient.getEntry(id)
  cache.set(id, entry)

  // Auto-clear cache after 5 minutes
  setTimeout(() => cache.delete(id), 5 * 60 * 1000)

  return entry
}

Use GraphQL for efficiency:

# Fetch only needed fields
query {
  blogPostCollection(limit: 10) {
    items {
      title
      slug
      publishDate
      # Only fields you need
    }
  }
}

Rich Text Rendering Issues

Problem: Rich Text content not rendering correctly.

Causes:

  • Missing node renderers
  • Embedded entries not resolved
  • Custom content types not handled
  • HTML sanitization stripping content

Solutions:

import { documentToReactComponents } from '@contentful/rich-text-react-renderer'
import { BLOCKS, INLINES } from '@contentful/rich-text-types'

const renderOptions = {
  renderNode: {
    [BLOCKS.EMBEDDED_ASSET]: (node) => {
      const { url, fileName } = node.data.target.fields.file
      return <img src={url} alt={fileName} />
    },
    [BLOCKS.EMBEDDED_ENTRY]: (node) => {
      const entry = node.data.target
      // Handle embedded entries
      return <EmbeddedContent entry={entry} />
    },
    [INLINES.HYPERLINK]: (node, children) => {
      return <a href={node.data.uri}>{children}</a>
    },
  },
}

export function RichTextContent({ content }) {
  return <>{documentToReactComponents(content, renderOptions)}</>
}

Environment Variable Issues

Problem: Wrong Contentful content appearing.

Causes:

  • Incorrect environment variables
  • Wrong space ID or access token
  • Build-time vs runtime variables
  • Environment not specified

Solutions:

# .env.local (for Next.js)
CONTENTFUL_SPACE_ID=your_space_id
CONTENTFUL_ACCESS_TOKEN=your_delivery_api_token
CONTENTFUL_PREVIEW_ACCESS_TOKEN=your_preview_api_token
CONTENTFUL_ENVIRONMENT=master

# .env.development
CONTENTFUL_ENVIRONMENT=staging

# .env.production
CONTENTFUL_ENVIRONMENT=master

Validate environment:

if (!process.env.CONTENTFUL_SPACE_ID) {
  throw new Error('CONTENTFUL_SPACE_ID is required')
}

if (!process.env.CONTENTFUL_ACCESS_TOKEN) {
  throw new Error('CONTENTFUL_ACCESS_TOKEN is required')
}

Debugging Tools

Browser Developer Tools

Chrome DevTools (F12):

  • Console: Check for JavaScript errors
  • Network: Verify Contentful API requests
  • Performance: Analyze load times
  • Application: Check localStorage, cookies

Contentful-Specific Tools

Contentful Web App:

  • Preview content before publishing
  • Check content model structure
  • View API keys and access tokens
  • Monitor API usage

Contentful CLI:

# Install CLI
npm install -g contentful-cli

# Login
contentful login

# Export content
contentful space export --environment-id master

# Clear cache
contentful space environment clear-cache

Analytics Debugging Tools

Browser Extensions:

Platform Tools:

  • GA4 DebugView
  • Meta Events Manager Test Events
  • GTM Preview Mode

Performance Testing Tools

Contentful GraphQL Explorer

Test GraphQL queries:

  1. Go to Contentful web app
  2. Navigate to Content model → GraphQL Playground
  3. Test queries before implementing in code
  4. Copy working queries to your application

Getting Help

Contentful Support Channels

Contentful Documentation:

Contentful Community:

Contentful Support:

  • Email support (all plans)
  • Priority support (Enterprise)
  • Support Portal

Stack Overflow:

  • Tag: contentful
  • Search existing questions
  • Ask new questions with code examples

When to Hire a Developer

Consider hiring a developer when:

  • Complex custom implementation required
  • Performance issues persist despite optimizations
  • Advanced caching strategies needed
  • Multi-environment setup required
  • Migration from another CMS
  • Custom Contentful app development

Finding Developers:

  • Contentful Partners
  • Framework-specific consultants (Next.js, Gatsby experts)
  • Freelance platforms (Upwork, Toptal)

Next Steps

Performance Issues:

Tracking Issues:

Prevention:

  • Document your Contentful content model
  • Test changes in preview/staging environment
  • Monitor performance regularly
  • Version control all configuration
  • Keep frameworks and dependencies updated

For platform-agnostic troubleshooting, see the global issues hub.

Nach oben