Troubleshooting

If none of these help, open an issue on GitHub. Please don’t paste passwords, tokens or feed URLs that contain ?token=.

Episodes aren’t downloading

Check your internet connection.
Check the RSS feed URL is correct.
Check the logs for error messages. Set PODVAULT_LOG_LEVEL=DEBUG for more detail, and PODVAULT_LOG_FILE to keep them in a file.
Make sure the downloads folder is writable. In Docker, that’s ./data/downloads on the host (or whatever you mounted on /app/data/downloads).

Tags aren’t updating

Check the file’s format: tags are only written for MP3 and M4A/M4B/MP4. Other formats are archived with the publisher’s tags as they are.
Check the audio file exists and is writable.
Check the logs for specific errors.
From source, make sure mutagen is installed. If you see a “mutagen library not available” warning, install it:
Terminal window
```
pip install mutagen
```

A podcast app can’t load my PodVault feed

Open the feed URL in your phone’s browser first. If it doesn’t load there, the phone can’t reach PodVault. Use the server’s LAN address instead of 127.0.0.1 or localhost, connect through your VPN if you’re away from home, or set PODVAULT_BASE_URL to the address the phone uses.
With the login on, copy the URL from the podcast’s page, including the ?token=… part. If you’ve changed the password since, copy it again: the old token no longer works.
Episodes only appear once they’re downloaded.

Database errors

Make sure PodVault can write to the folder the database is in.
Check the database file isn’t locked by another process, for example a CLI command running while podvault serve is writing.
Check PODVAULT_DB_PATH points where you expect. In Docker it’s /app/data/podvault_data.db, which is ./data/podvault_data.db on the host.
If the database is damaged or something went wrong after a sync, restore the latest backup from backups/.

Check your browser accepts cookies for PodVault’s address. The sign-in is kept in a podvault_session cookie.
If you changed PODVAULT_PASSWORD or PODVAULT_USERNAME, everyone has to sign in again. That’s intended.
Check PODVAULT_USERNAME and PODVAULT_PASSWORD are set the way you think. The Settings page shows the username and whether a password is set, never the password itself.
If the sign-in page says “Login is misconfigured”, only one of the two variables is set. Set both, or neither.
If sign-in is refused even with the right password, you may be locked out after too many wrong attempts. Wait: the lockout starts at 30 seconds and grows to at most 15 minutes. See Login lockout.

Files I downloaded are in the old folder layout

Changing a naming template only affects new downloads. Run podvault migrate-layout to see what would move, then podvault migrate-layout --apply. See migrate-layout.

Auto-refresh isn’t running

Schedules only run while the web server is running (podvault serve, or the Docker container). They don’t run from plain CLI commands, and podvault serve --reload skips them. The Schedule page shows whether the scheduler is running.

“Download latest” picked an old episode

Before 1.3.1, feed dates were sorted as text, so “latest” could pick an older episode. Update to the current version. See the release notes.

PodVault v1.3.1 · GitHub · Docker Hub ·Report an issue