Troubleshooting¶

This section covers common issues and their solutions.

Image Renditions¶

Missing or broken images¶

If images appear broken or missing on the frontend:

Ensure renditions have been generated:
```
python manage.py sync_renditions
```
If you recently changed CAST_REGULAR_IMAGE_SLOT_DIMENSIONS or CAST_GALLERY_IMAGE_SLOT_DIMENSIONS, run sync_renditions again. It will create missing renditions and delete obsolete ones.

For a specific post or blog:

python manage.py sync_renditions --post-slug my-post
python manage.py sync_renditions --blog-slug my-blog

Stale Vite Assets¶

If you see Django system check warning cast.W001, your Vite-built JavaScript assets are older than the JavaScript source files. Rebuild them:

just js-build-vite
# or to rebuild all JavaScript assets:
just js-build-all

This regenerates the image gallery and Podlove audio player bundles.

Audio and Podcasts¶

Missing audio duration¶

Audio duration is computed automatically when an audio object is saved. If duration is missing for older files, re-save the audio object in the Wagtail or Django admin to trigger recomputation.

Chapter marks not appearing¶

Chapter marks can be entered manually or extracted automatically from audio file metadata via ffprobe. Ensure ffprobe (part of the FFmpeg package) is installed on your system if you want automatic extraction.

Video poster images also require ffmpeg. See recalc_video_posters for regenerating posters.

Media Storage¶

Production images deleted from development¶

If you share a storage backend (e.g., S3 bucket) between environments, set in your development settings:

DELETE_WAGTAIL_IMAGES = False

This prevents Wagtail from deleting the original image file on S3 when an image model is removed locally.

Also be careful with storage-management commands such as python manage.py media_stale --delete. They operate on the configured production storage backend and can remove real files if your local or staging environment points at shared production storage.

Finding unreferenced media files¶

Over time, media files may accumulate that are no longer referenced by any database record. To find them:

python manage.py media_stale

To also delete them:

python manage.py media_stale --delete

Themes and Templates¶

Theme not applying¶

Theme resolution follows this precedence (highest wins):

Internal request.cast_template_base_dir override (used by styleguide)
?theme= or ?template_base_dir= query parameter (temporary preview)
Django session value (persistent user choice via theme selector)
Blog-level template_base_dir field
Site-level TemplateBaseDirectory Wagtail setting

If a theme is not applying:

Check whether a query parameter or session value is overriding the blog/site default.
Verify that the theme was actually discovered by django-cast.
Ensure the template directory exists at cast/<theme_name>/ within one of your installed apps’ template directories.
Confirm that the theme contains the required templates described in Templates / Themes.

Spam Filter¶

Poor spam detection accuracy¶

The built-in Naive Bayes spam filter improves with training data. To retrain it from scratch using existing comment classifications:

Go to Django Admin > Spam Filters
Select your spam filter
Use the “Retrain model from scratch using marked comments” action

The filter’s precision and recall metrics are shown in the admin list view.

Comments Not Appearing¶

If comments are not visible on posts:

Verify CAST_COMMENTS_ENABLED = True in settings
Check that comments_enabled = True on the specific Blog page
Ensure the commenting app is in INSTALLED_APPS (included automatically via CAST_APPS)

Video Poster Images¶

If video poster images are missing or incorrect, regenerate them:

python manage.py recalc_video_posters

This requires ffmpeg to be installed on your system.