Ghost Integration Troubleshooting Guide

Common Issues and Solutions

1. Connection Issues

"Invalid API Key" Error

Symptoms:

• Integration fails to connect
• Error message: "Please enter a valid Ghost Admin API Key (format: id:secret)"

Causes:

• Incorrect API key format
• Copied key with extra spaces or characters
• Expired or revoked API key

Solutions:

1. Verify API Key Format

   Correct format: 64a1f2b3c4d5e6f7:a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6
   Incorrect: Missing colon, extra spaces, or truncated key

2. Re-generate API Key

   • Go to Ghost Admin → Settings → Integrations
   • Delete the existing custom integration
   • Create a new integration
   • Copy the new API key carefully

3. Check for Hidden Characters

   • Paste the API key into a plain text editor first
   • Remove any line breaks or spaces

• Copy the clean key to Bloggy AI

"Invalid URL" Error

Symptoms:

• Error message: "Please enter a valid URL (e.g., https://yourblog.ghost.io)"
• Connection test fails

Causes:

• Missing protocol (http/https)
• Incorrect URL format
• Typos in domain name
• Wrong subdirectory path

Solutions:

1. Verify URL Format

   ✅ Correct formats:
   - https://yourblog.ghost.io
   - https://yourdomain.com
   - https://yourdomain.com/blog
   
   ❌ Incorrect formats:
   - yourblog.ghost.io (missing protocol)
   - https://yourblog.ghost.io/ghost/ (includes /ghost/)
   - http://yourblog.ghost.io (should use https)

2. Test URL Manually

   • Open the URL in your browser
   • Ensure it loads your Ghost site
   • Check for redirects or SSL issues

2. Publishing Issues

"Post Creation Failed" Error

Symptoms:

• Posts fail to publish to Ghost
• Error in Bloggy AI dashboard
• No post appears in Ghost admin

Causes:

• Insufficient API permissions
• Ghost site maintenance
• Content formatting issues
• Network connectivity problems

Solutions:

1. Check API Permissions

   • Verify the integration has Admin API access
   • Ensure the API key hasn't been revoked
   • Test with a simple post first

2. Validate Content

   • Check for unsupported HTML tags
   • Ensure images are accessible
   • Verify content length limits

3. Retry Publishing

   • Wait a few minutes and retry
   • Check Ghost site status
   • Contact support if issue persists

"Featured Image Upload Failed"

Symptoms:

• Post publishes but without featured image
• Image upload error in logs

Causes:

• Image file too large
• Unsupported image format
• Network timeout
• Ghost storage limits

Solutions:

1. Check Image Requirements

   Supported formats: JPG, PNG, GIF, WebP
   Maximum size: 10MB (varies by Ghost plan)
   Recommended: 1200x630px for social sharing

2. Optimize Images

   • Compress images before upload
   • Use web-optimized formats
   • Ensure stable internet connection

3. Authentication Issues

"API Key Expired" Error

Symptoms:

• Previously working integration stops functioning
• Authentication errors in logs

Causes:

• API key manually revoked in Ghost
• Ghost site migration or updates
• Security policy changes

Solutions:

1. Regenerate API Key
   • Create new custom integration in Ghost

• Update API key in Bloggy AI
  • Test connection

2. Check Ghost Admin
   • Verify integration still exists
   • Check for any security notifications
   • Review recent Ghost updates

4. Content Formatting Issues

"HTML Parsing Error"

Symptoms:

• Content appears broken in Ghost
• Missing formatting or images
• Unexpected layout issues

Causes:

• Unsupported HTML elements
• Malformed markup
• CSS conflicts

Solutions:

1. Validate HTML

   • Use HTML validator tools
   • Remove unsupported tags
   • Simplify complex formatting

2. Test with Simple Content

   • Try publishing plain text first
   • Gradually add formatting
   • Identify problematic elements

5. Network and Connectivity Issues

"Connection Timeout" Error

Symptoms:

• Intermittent connection failures
• Slow publishing times
• Network-related errors

Causes:

• Slow internet connection
• Ghost server issues
• Firewall restrictions
• DNS problems

Solutions:

1. Check Network Connection

   • Test internet speed
   • Try different network
   • Disable VPN if active

2. Verify Ghost Site Status

   • Check Ghost status page
   • Test site accessibility
   • Contact Ghost support if needed

Diagnostic Steps

Step 1: Basic Connectivity Test

1. Open your Ghost site URL in browser
2. Verify SSL certificate is valid
3. Check if Ghost admin is accessible
4. Test API endpoint manually (if technical)

Step 2: API Key Validation

1. Copy API key to plain text editor
2. Verify format: id:secret with colon separator
3. Ensure no extra spaces or characters
4. Check key length (should be long string)

Step 3: Integration Test

1. Create new test integration in Bloggy AI
2. Use minimal configuration
3. Test with simple content
4. Monitor error messages carefully

Step 4: Content Analysis

1. Try publishing plain text post
2. Add formatting gradually
3. Test with different content types
4. Identify specific problematic elements

Prevention Best Practices

Regular Maintenance

• Monthly: Check integration status
• Quarterly: Rotate API keys for security
• After Ghost Updates: Verify integration still works
• Before Important Campaigns: Test publishing workflow

Security Measures

• Never share API keys publicly
• Use descriptive integration names
• Monitor integration activity in Ghost admin
• Revoke unused integrations promptly

Content Guidelines

• Keep HTML simple and clean
• Optimize images before publishing
• Test formatting in Ghost preview
• Use supported content elements only

Error Code Reference

Error Code	Description	Solution
AUTH_001	Invalid API Key Format	Check key format (id:secret)
AUTH_002	API Key Expired/Revoked	Regenerate API key
CONN_001	Invalid URL Format	Verify URL format and protocol
CONN_002	Connection Timeout	Check network and Ghost status
PUB_001	Post Creation Failed	Check API permissions
PUB_002	Content Validation Error	Simplify content formatting
IMG_001	Image Upload Failed	Check image size and format
IMG_002	Image Processing Error	Optimize image before upload

Getting Additional Help

Before Contacting Support

1. Gather Information

   • Error messages (exact text)
   • Integration configuration (without API key)
   • Ghost version and plan type
   • Recent changes to setup

2. Try Basic Solutions

   • Regenerate API key
   • Test with simple content
   • Check Ghost site status
   • Verify network connectivity

Contact Information

• Bloggy AI Support: Include integration ID and error details
• Ghost Support: For Ghost-specific issues and API problems
• Community Forums: For general troubleshooting and tips

Useful Resources

• Ghost API Documentation
• Ghost Status Page
• Bloggy AI Documentation
• Ghost Community Forum

---

Last updated: March 2024