Troubleshooting

If something's not right, this is the checklist. Common misconfigurations first, weirder ones after.

My homepage doesn't show any episodes

Pod filters the homepage archive by the internal tag #podcast. Every episode post has to carry it, or it doesn't show up.

Fix: Open each episode post, click the settings cog, add the tag #podcast (typed with the hash — Ghost treats hash-prefixed tags as internal, meaning they don't appear on the public tag page but still filter feeds and collections).

The RSS feed at /podcast/rss/ returns a 404

Pod needs a routes.yaml that includes the /podcast/rss/ and /subscribe/ route entries. Without it, both URLs return Ghost's default 404 page.

Fix: Download Pod's routes.yaml from the latest GitHub release. In Ghost admin → Settings → Labs → Upload routes.yaml, upload it. If you've customised your routes previously, follow the "merge" branch in the Getting started doc instead of overwriting.

The RSS feed loads but has no episodes

Same tag issue as the homepage. The feed template's query is tag:hash-podcast, matching the internal #podcast tag on episode posts.

Fix: Add #podcast as an internal tag to every episode. Refresh /podcast/rss/ and the items should now appear.

Audio plays but the RSS enclosure says length="0"

Pod can't know your audio file's size unless you tell it. Podcast apps use the file-size length attribute for download-progress bars, and strict validators flag it as a warning when it's missing.

Fix: Use the episode metadata generator's Fetch from URL button — it HEAD-requests your MP3 and fills in the file size automatically. Or add the <!-- pod:audioLength=BYTES --> marker manually to your episode's code injection foot.

Audio doesn't play on the site

Three usual causes:

1. MIME type. Some CDNs / self-hosted setups serve MP3s with the wrong Content-Type. Browsers refuse to play audio that isn't served as audio/mpeg or a similar audio MIME.
   Check: curl -I https://your-audio-url/ep01.mp3. If the content-type header isn't audio/mpeg, fix it on the audio host's side.
2. CORS. If your audio is on a different host than your Ghost site, and that host doesn't allow cross-origin fetches, the player can play the file but the "Fetch from URL" button in the generator won't work. Playback itself doesn't require CORS on modern browsers; only the file-size HEAD request does.
   Check: the browser dev tools' Network tab shows CORS errors under the failing request.
3. Mixed content. Serving audio over http:// from a Ghost site on https:// — browsers block this.
   Fix: use HTTPS for the audio host, or upload the file to Ghost.

My episode's cover art is the wrong image

Pod's cover-art resolution order (both for the /podcast/rss/ feed and the on-site archive card):

1. Ghost's feature image on the post — this is what shows up if you set one.
2. If no feature image, Pod's CSS-rendered fallback tile takes over on the site (gradient + episode number). In the RSS feed, Pod falls back to the theme-shipped default cover at /assets/img/default-cover.jpg.

Fix: Set a per-episode feature image in the post's settings. Apple recommends 1400×1400 to 3000×3000 pixels, JPG or PNG, under 512 KB. Pod uses the same image for both the on-page cover and the RSS <itunes:image>.

Apple Podcasts rejected my submission

Common reasons:

• Cover art too small, too big, or wrong format. Must be 1400×1400 min, 3000×3000 max, JPG or PNG, RGB, under 512 KB. Pod's default cover meets these, but if you've uploaded a custom one, double-check.
• iTunes explicit flag not set. Apple requires an explicit yes/no answer, no "unknown". Set itunes_explicit in Ghost admin.
• Owner email verification failed. The email in itunes_owner_email must be a real inbox — Apple sends a verification code to it. Check spam.
• Category missing or invalid. Set itunes_category in Ghost admin to one of Apple's official categories.
• Show title too long (limit is 60 chars for the show title, 250 chars for episode titles).

The subscribe page shows apps I don't want

The ten open-catalog apps (Apple, Overcast, Pocket Casts, Castro, Podcast Addict, AntennaPod, Podverse, Player FM, gPodder, RSS) always render. That's by design — publishers shouldn't have to hand-configure every app, and the deep-link URL is derived from the RSS feed URL. The six closed-catalog apps (Spotify, Amazon, YouTube Music, iHeart, Castbox, Pandora) only appear when you paste in their respective show URLs.

What you can control: the closed-catalog buttons. Leave those settings empty in Ghost admin → Settings → Design → Site-wide and the corresponding buttons don't render.

Hiding the ten always-on apps isn't currently possible via custom settings; if you have a strong reason (a listener demographic that's exclusively on one app, or a partnership requirement), edit partials/subscribe-grid.hbs in the theme.

Chapters don't show up in podcast apps

Chapters need to be in the code-injection foot as repeated pod:chapter= markers. Two things to check:

1. Format: <!-- pod:chapter=HH:MM:SS|Chapter title -->. Note the | separator between timestamp and title. Leading zeros aren't required — 0:05:30 works.
2. App support: not every podcast app renders chapters. Apple Podcasts, Overcast, Pocket Casts, and Spotify do. Some smaller apps don't. That's not a Pod problem; it's an ecosystem limitation.

The Ghost admin says my theme has warnings after upload

Pod is gscan-validated against Ghost 6.x with zero warnings. If your Ghost install shows warnings on upload, one of two things happened:

1. You're on an older Ghost (below 5.93) that doesn't recognise all of Pod's helpers. Upgrade Ghost.
2. Ghost's gscan version disagrees with the version we test against. Check the specific warnings — if they're about Ghost 7 forward-compatibility, they're informational and won't affect functionality until a future Ghost major release.

Something else

If this doc doesn't cover your situation, the fastest path is:

• Open an issue on GitHub — bug reports and feature requests both welcome.
• Email help@magicpages.co — Magic Pages customers get direct support; anyone else gets a best-effort reply.
• Check the Ghost forum for anything about Ghost itself (routes.yaml behaviour, custom template rules, general theme development).