Troubleshooting

Having issues with your theme? Here are solutions to the most common problems.

Installation Issues#

Theme won't upload#

If you're having trouble uploading the theme:

1. Check the file size — Ghost has a limit on upload sizes. If using Ghost(Pro), the limit is typically 50MB.
2. Verify the ZIP file — Make sure you're uploading the original echo.zip file, not a folder or extracted files.
3. Check Ghost version — Ensure you're running Ghost 5.x or later.
4. Clear browser cache — Try a hard refresh (Ctrl+Shift+R or Cmd+Shift+R).

Theme activates but looks broken#

If the theme installs but doesn't display correctly:

1. Upload routes.yaml — Go to Settings → Advanced → Labs and upload the routes.yaml file included with your theme.
2. Clear cache — Clear your browser cache and any caching plugins.
3. Check for custom code — Temporarily remove any code from Code Injection to rule out conflicts.

Content Display Issues#

Posts not showing on homepage#

If your posts aren't appearing:

1. Check post status — Make sure posts are published, not drafts.
2. Verify routes.yaml — Ensure the routes.yaml file is uploaded correctly.
3. Check internal tags — Some sections require specific internal tags (starting with #).
4. Clear cache — Try clearing your browser cache.

Featured posts not appearing#

Featured posts require proper setup:

1. Go to Settings → Design → Customize → Theme
2. Enable the featured posts section
3. Mark posts as "Featured" in the post settings
4. Make sure you have at least one featured post published

Images not displaying#

If images aren't showing:

1. Check image format — Use standard formats (JPG, PNG, WebP, GIF).
2. Verify image size — Very large images may fail to load.
3. Check image URLs — Ensure images are properly uploaded to Ghost.
4. Clear CDN cache — If using a CDN, clear the cache.

Navigation Issues#

Menu not showing#

If your navigation menu is empty:

1. Go to Settings → Navigation
2. Add menu items with labels and URLs
3. Click Save
4. Refresh your site

Dropdown menus not working#

For dropdown menus to work:

1. Add a main menu item (parent)
2. Add secondary navigation items for dropdowns
3. Check the Navigation documentation for detailed setup

Styling Issues#

Dark mode not working#

If dark mode toggle isn't appearing or functioning:

1. Check that dark mode is enabled in Settings → Design → Customize → Theme
2. Clear browser cache
3. Try in an incognito/private window
4. See Dark Mode documentation

Custom fonts not loading#

If custom fonts aren't displaying:

1. Verify the font file URLs are correct
2. Check that fonts are in supported formats (WOFF2, WOFF)
3. Ensure fonts are properly hosted and accessible

Layout looks different than demo#

If your site doesn't match the demo:

1. Check theme settings — Go through all options in Design → Customize → Theme
2. Verify routes.yaml — Different routes create different layouts
3. Review content structure — The demo uses specific content setups

Member & Subscription Issues#

Subscription form not working#

If the newsletter form isn't submitting:

1. Ensure Members is enabled in Ghost settings
2. Check that the portal is properly configured
3. Verify you're not blocking the Ghost portal script

Member-only content showing to everyone#

If content gating isn't working:

1. Check post visibility settings in the post editor
2. Verify the member tier has proper access settings
3. Make sure the user isn't logged in as a member

Performance Issues#

Slow page loading#

If your site loads slowly:

1. Optimize images — Use compressed images and appropriate sizes
2. Minimize code injection — Large scripts can slow down loading
3. Check hosting — Server response time affects loading
4. Use a CDN — Content delivery networks speed up asset loading
5. Enable caching — Use browser and server-side caching

High server resource usage#

If the theme uses excessive resources:

1. Reduce the number of posts per page in Ghost settings
2. Optimize images before uploading
3. Remove unused custom code from Code Injection

Common Error Messages#

"Failed to install theme"#

This usually means:

• The theme file is corrupted — try re-downloading
• Ghost version is incompatible — update Ghost
• File size exceeds limit — check hosting limits

"Template error" in console#

If you see template errors:

1. Update to the latest theme version
2. Check if all required routes are configured
3. Verify Ghost version compatibility

Still Having Issues?#

If you've tried these solutions and still have problems:

1. Check the FAQ for more answers
2. Review the complete documentation
3. Contact our support team with:
   • Your Ghost version
   • Theme version
   • Detailed description of the issue
   • Screenshots if applicable
   • Any error messages you're seeing