Kontent.ai (Kentico Kontent) Troubleshooting | OpsBlu Docs

Kontent.ai (Kentico Kontent) Troubleshooting

Debug analytics issues on Kontent.ai — Delivery API integration, preview environment conflicts, webhook rebuild timing, and structured content...

Kontent.ai (formerly Kentico Kontent) is a headless CMS with a structured content model and Delivery/Management APIs. Since Kontent.ai has no frontend, analytics issues always trace to your frontend framework's integration with the Kontent.ai Delivery API. The CMS delivers structured JSON; your code renders the HTML and tracking scripts.

Kontent.ai-Specific Debugging Approach

Debugging analytics on a Kontent.ai site means checking the API layer and your frontend rendering independently.

Verify Delivery API Responses

# Check if Kontent.ai delivers your analytics configuration
curl -s "https://deliver.kontent.ai/[project-id]/items/site-settings" \
  -H "Authorization: Bearer [preview-key]" | python3 -m json.tool | grep -i "tracking\|analytics\|gtm"

// In browser console, check what reached the frontend
console.log('Analytics scripts found:', document.querySelectorAll('script[src*="gtag"], script[src*="gtm"]').length);

// For Next.js + Kontent.ai sites
console.log('Kontent data:', window.__NEXT_DATA__?.props?.pageProps ? 'present' : 'missing');

Check Content Item Publication Status

Kontent.ai has a workflow system. Content items must be in the "Published" workflow step for the Delivery API to return them in production:

# Check published vs. draft content
# Published Delivery API (production):
curl -s "https://deliver.kontent.ai/[project-id]/items/site-settings" \
  | python3 -m json.tool | grep "tracking_id"

# Preview Delivery API (draft):
curl -s "https://preview-deliver.kontent.ai/[project-id]/items/site-settings" \
  -H "Authorization: Bearer [preview-key]" \
  | python3 -m json.tool | grep "tracking_id"

Most Common Kontent.ai Analytics Issues

1. Content Item Not Published in Workflow

Symptoms: Analytics configuration visible in the Kontent.ai app but missing on the production site. Works in preview.

Root cause: The content item containing analytics settings is in a draft or review workflow step. Only "Published" items appear in the production Delivery API.

Fix: In the Kontent.ai app, navigate to the content item (e.g., "Site Settings"), and move it through the workflow to "Published." Ensure all linked items are also published.

2. Delivery API Returning Partial Data

Symptoms: Some analytics fields are populated, others are empty. The tracking ID loads but custom scripts do not.

Root cause: Kontent.ai's Delivery API only returns elements that have content. Empty fields are omitted from the response entirely, which can cause undefined errors in your frontend.

Fix: Always provide defaults when accessing Kontent.ai field values:

// Safe field access pattern for Kontent.ai responses
const settings = kontentResponse.item;
const trackingId = settings.elements.tracking_id?.value || process.env.NEXT_PUBLIC_GA_ID;
const customScript = settings.elements.custom_head_script?.value || '';

if (trackingId) {
  // Initialize analytics
}

3. Preview Environment Inflating Analytics Data

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

Root cause: Kontent.ai's preview functionality loads your frontend with the preview API. If analytics is not suppressed, editorial previews generate real tracking data.

Fix:

// Detect Kontent.ai preview mode
const isKontentPreview = new URLSearchParams(window.location.search).has('preview') ||
  process.env.NEXT_PUBLIC_KONTENT_PREVIEW === 'true';

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

4. Rich Text Element Stripping Script Tags

Symptoms: Analytics code embedded in a Rich Text element does not render on the frontend.

Root cause: Kontent.ai Rich Text elements store structured HTML. Most SDK resolvers and frontend renderers strip <script> tags from Rich Text content for security reasons.

Fix: Use a dedicated text or custom element for analytics code, not Rich Text:

// In your Kontent.ai content type, use:
// - "Text" element for tracking IDs
// - "Custom element" for script snippets
// NOT "Rich text" — it strips scripts

// Then in your frontend layout:
const headScript = siteSettings.elements.head_script_code?.value;
if (headScript) {
  // Inject as raw HTML in your layout's <head>
}

5. Webhook Rebuild Timing Gaps

Symptoms: Content published in Kontent.ai but the live site serves stale analytics configuration for several minutes.

Root cause: Static site generators (Gatsby, Next.js static export) rebuild on Kontent.ai webhook triggers, but the build + deploy pipeline takes time.

Fix: Use Kontent.ai's webhook with on-demand revalidation:

// Next.js API route for Kontent.ai webhook
export default async function handler(req, res) {
  const notification = req.body;
  // Check if the changed item is site-settings
  const isSettings = notification.data?.items?.some(
    item => item.codename === 'site_settings'
  );
  if (isSettings) {
    await res.revalidate('/');
    return res.json({ revalidated: true });
  }
  return res.json({ revalidated: false });
}

Environment Considerations

  • Kontent.ai is SaaS: No server to manage. Caching and CDN issues are on your frontend hosting side
  • Delivery API CDN: Kontent.ai caches Delivery API responses at their CDN layer. After publishing, API responses may take a few seconds to update
  • Structured content model: Analytics configuration should be in a dedicated content type (singleton pattern), not mixed into page content types
  • Environments: Kontent.ai supports project environments (Production, Staging). Ensure your production site fetches from the production environment
  • SDKs: Official SDKs exist for JavaScript, .NET, Java, and PHP. Each SDK handles field access slightly differently

Performance Issues

Tracking Issues

  • Events Not Firing - Debug workflow publishing, API field access, and preview mode leakage
Back to top