Ghost Troubleshooting Overview | OpsBlu Docs

Ghost Troubleshooting Overview

Common Ghost website issues, performance problems, and tracking errors with solutions

Ghost websites may encounter performance issues, tracking failures, and integration problems. This guide provides systematic approaches to diagnose and resolve common Ghost-specific issues.

Common Issue Categories

Performance Issues

Tracking and Analytics Issues

  • Events Not Firing - GA4, Meta Pixel, GTM integration problems
  • Duplicate Tracking - Multiple pixel fires, code injection conflicts
  • Missing Data - Member context issues, cache problems, ad blockers
  • Incorrect Attribution - Cross-domain tracking, referrer issues
  • Data Layer Errors - GTM variable problems, Handlebars issues

Integration Problems

  • Code Injection Failures - Syntax errors, Ghost cache, Handlebars limitations
  • Theme Modification Issues - Upload errors, activation failures, Ghost version conflicts
  • Ghost Portal Conflicts - Member widget issues, payment failures, styling conflicts
  • API Rate Limits - Content API throttling, Admin API restrictions
  • Webhook Failures - Stripe integration issues, server connectivity problems

Content and Member Issues

  • Member Access Problems - Login failures, content visibility, tier restrictions
  • Email Delivery Issues - Newsletter failures, SMTP configuration, bounce handling
  • Search Not Working - Ghost search configuration, index problems
  • Image Optimization - Large images, format issues, responsive images
  • SEO Problems - Meta tags, structured data, sitemap generation

Systematic Troubleshooting Approach

Step 1: Identify the Problem

Collect Information:

  • What is the expected behavior?
  • What is the actual behavior?
  • When did the problem start?
  • Does it affect all users or specific segments?
  • Is it reproducible consistently?

Check Error Messages:

# Self-hosted Ghost: Check logs
ghost log

# Or direct log access
tail -f /var/www/ghost/content/logs/*.log

# Browser console errors
# Open DevTools → Console
# Look for red error messages

Step 2: Isolate the Cause

Test in Different Contexts:

  • Incognito/private browsing (eliminates extensions)
  • Different browsers (Chrome, Firefox, Safari)
  • Different devices (desktop, mobile, tablet)
  • Logged in vs. logged out (member context)
  • Different networks (home, office, mobile data)

Disable Potential Conflicts:

  • Temporarily remove code injection
  • Test with default Ghost theme
  • Disable browser extensions
  • Pause CDN/caching temporarily

Step 3: Review Recent Changes

Check Ghost Admin:

  • Recent theme uploads
  • Code injection modifications
  • Integration additions
  • Ghost version updates
  • Member tier changes

Review Analytics Platforms:

  • GTM container changes
  • GA4 configuration updates
  • Meta Pixel modifications
  • Tag changes or deletions

Step 4: Verify Configuration

Ghost Settings:

  • Settings → General - Site URL, timezone, language
  • Settings → Code Injection - Syntax errors, script conflicts
  • Settings → Labs - Feature flags, API access
  • Settings → Integrations - Active integrations, webhooks

Theme Configuration:

  • Verify theme version compatibility
  • Check package.json for Ghost version requirement
  • Review default.hbs, post.hbs, page.hbs for errors

Step 5: Test and Validate

Performance Testing:

Tracking Validation:

  • Google Tag Assistant
  • Meta Pixel Helper
  • GA4 DebugView
  • GTM Preview Mode

Quick Diagnostic Checklist

Ghost Site Not Loading

  • Check Ghost service status (ghost status for self-hosted)
  • Verify DNS settings and domain configuration
  • Check SSL certificate validity
  • Review server resources (CPU, memory, disk space)
  • Check database connection
  • Review Ghost logs for errors

Tracking Not Working

  • Verify tracking code present in page source (View Source)
  • Check browser console for JavaScript errors
  • Test with ad blockers disabled
  • Verify measurement IDs/pixel IDs correct
  • Check GTM container published (if using GTM)
  • Test in incognito mode
  • Verify data layer populates (for GTM)

Performance Issues

  • Run Lighthouse audit
  • Check image sizes and formats
  • Review number of HTTP requests
  • Test with caching disabled
  • Verify CDN configuration
  • Check for render-blocking resources
  • Review JavaScript bundle size

Member/Portal Issues

  • Verify Ghost Members enabled (Settings → Membership)
  • Check Stripe integration configured
  • Test Portal in different browsers
  • Review browser console for errors
  • Verify email configuration
  • Check member tier settings
  • Test with different member states

Common Ghost-Specific Issues

Issue: Ghost Cache Not Clearing

Symptoms:

  • Old content still showing after updates
  • Code injection changes not appearing
  • Theme modifications not visible

Solutions:

For Ghost(Pro):

# Ghost(Pro) automatically handles caching
# Wait 5-10 minutes for CDN refresh
# Or contact Ghost support to force cache clear

For Self-Hosted:

# Restart Ghost
ghost restart

# Clear Redis cache (if using Redis)
redis-cli FLUSHALL

# Clear Varnish cache (if using Varnish)
varnishadm ban req.url "~" "."

# Clear Nginx cache
rm -rf /var/cache/nginx/*
nginx -s reload

Issue: Handlebars Helpers Not Working

Symptoms:

  • \{\{@member\}\} not populating
  • \{\{#post\}\} context missing
  • Custom helpers undefined

Solutions:

  • Verify helpers used in correct context (post.hbs vs. default.hbs)
  • Check Ghost version supports the helper
  • Review Ghost Handlebars documentation
  • Test in theme partials vs. code injection (limited support in code injection)

Issue: Ghost Portal Not Appearing

Symptoms:

  • Member signup widget missing
  • Portal button doesn't open
  • Portal styling broken

Solutions:

  1. Verify Members Enabled:

    • Navigate to Settings → Membership
    • Ensure "Members" toggle is ON

  2. Check Portal Configuration:

// In browser console, check Portal settings
console.log(window.ghost);
// Should show Portal configuration
  1. Verify Portal Script Loads:
// Check for Portal script
console.log(document.querySelector('script[src*="portal"]'));
// Should return script element
  1. Fix Portal Styling Conflicts:
/* In theme CSS, ensure no conflicts */
.ghost-portal-frame {
  z-index: 9999 !important;
}

Issue: Ghost Admin API Rate Limiting

Symptoms:

  • 429 Too Many Requests errors
  • API calls failing intermittently
  • Webhook failures

Solutions:

Rate Limits:

  • Content API: 10,000 requests per hour
  • Admin API: 1,000 requests per hour

Implement Rate Limiting:

const rateLimit = require('express-rate-limit');

const apiLimiter = rateLimit({
  windowMs: 60 * 60 * 1000, // 1 hour
  max: 900, // Stay under 1000/hour limit
  message: 'Too many requests, please try again later.'
});

app.use('/api/', apiLimiter);

Cache API Responses:

const NodeCache = require('node-cache');
const cache = new NodeCache({ stdTTL: 600 }); // 10 minute cache

async function getCachedPosts() {
  const cached = cache.get('posts');
  if (cached) return cached;

  const posts = await api.posts.browse();
  cache.set('posts', posts);
  return posts;
}

Ghost Version-Specific Issues

Ghost 5.x Issues

Theme Compatibility:

  • Ensure theme supports Ghost 5.x in package.json
  • Update Handlebars syntax for new helpers
  • Review breaking changes in Ghost 5.0 migration guide

Member Tiers:

  • Ghost 5.x introduced multiple tiers
  • Update tracking code for @member.subscriptions (array, not single object)
  • Review tier-based content access

Ghost 4.x to 5.x Migration

Common Problems:

{{!-- Ghost 4.x (deprecated) --}}
{{@member.subscription}}

{{!-- Ghost 5.x (correct) --}}
{{@member.subscriptions.[0]}}

Debugging Tools and Resources

Browser DevTools

Console:

// Check for errors
// Open DevTools → Console → Look for red errors

// Verify tracking functions exist
console.log(typeof gtag); // "function"
console.log(typeof fbq);  // "function"
console.log(typeof dataLayer); // "object"

Network Tab:

// Monitor tracking requests
// DevTools → Network → Filter by "google-analytics" or "facebook"
// Verify requests send successfully (200 status)

Application Tab:

// Check cookies and localStorage
// DevTools → Application → Cookies
// Verify _ga, _fbp, ghost-members-ssr cookies

Ghost CLI Diagnostics

# Check Ghost status
ghost status

# View Ghost logs
ghost log

# Run Ghost doctor (checks configuration)
ghost doctor

# Check Ghost version
ghost version

# Test database connection
ghost setup

# Update Ghost
ghost update

Performance Monitoring

Core Web Vitals:

Monitoring Tools:

Getting Additional Help

Ghost Support Resources

Official Documentation:

Community Support:

Ghost(Pro) Support:

  • Email: support@ghost.org
  • Available 24/7 for Ghost(Pro) customers
  • Response time: Usually within 24 hours

Analytics Platform Support

Google Analytics:

Google Tag Manager:

Meta:

Specific Troubleshooting Guides

For detailed solutions to specific problems:

Preventive Maintenance

Regular Health Checks

Weekly:

  • Review Ghost logs for errors
  • Check uptime monitoring reports
  • Verify backup completion
  • Test critical user flows (signup, login, purchase)

Monthly:

  • Run Lighthouse performance audit
  • Review tracking accuracy in analytics platforms
  • Test all integrations (Stripe, email, webhooks)
  • Update Ghost and themes to latest versions
  • Review and optimize database

Quarterly:

  • Comprehensive security audit
  • Review and update SSL certificates
  • Performance optimization review
  • User experience testing
  • Disaster recovery testing

Monitoring Setup

Uptime Monitoring:

Error Tracking:

Performance Monitoring:

शीर्ष पर वापस जाएँ