> ## Content Index > Fetch the complete content index at: https://www.magicpages.co/llms.txt > Use this file to discover other available public pages before exploring further. # Troubleshooting - URL: https://www.magicpages.co/themes/pod/docs/troubleshooting/ - Published: 2026-07-13T07:23:06.000Z - Updated: 2026-07-13T07:34:06.000Z - Description: Common Pod problems and their fixes — missing episodes on the homepage, a 404 at /podcast/rss/, Apple submission rejections, audio that won't play, chapters not appearing, and the rest. - Author: Jannis Fedoruk-Betschki - Tags: #help-pod 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](https://github.com/magicpages/pod/releases/latest?ref=magicpages.co) 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](https://www.magicpages.co/themes/pod/docs/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](https://www.magicpages.co/themes/pod/docs/episode-metadata-generator/)'s *Fetch from URL* button — it HEAD-requests your MP3 and fills in the file size automatically. Or add the `` 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 ``. ## 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:** ``. 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](https://github.com/magicpages/pod/blob/main/CHANGELOG.md?ref=magicpages.co) 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](https://github.com/magicpages/pod/issues?ref=magicpages.co) — bug reports and feature requests both welcome. - [Email help@magicpages.co](mailto:help@magicpages.co) — Magic Pages customers get direct support; anyone else gets a best-effort reply. - Check the [Ghost forum](https://forum.ghost.org/?ref=magicpages.co) for anything about Ghost itself (routes.yaml behaviour, custom template rules, general theme development).