Symptoms · checks · recovery
Codex theme troubleshooting: backgrounds, imports, updates and recovery
Diagnose a Codex or WorkBuddy theme that does not appear, animate, import or survive an update, with safe stop, check and recovery steps.
Reviewed
Theme or background does not appear
Confirm that the package targets the application you opened: Codex and WorkBuddy packages are not interchangeable. Confirm macOS and the exact client version, then check that the matching adapter is marked verified.
- Reopen the package in Studio to confirm its target
- Check the static fallback image first
- Do not force an unknown build or rename a package to bypass target checks
Video, ripple or directional mode is static
Reduced Motion intentionally disables ripple and pins a directional atlas to its idle frame. For video, check that the asset is an MP4 inside the published size limit and that the target package actually includes it.
- Check the operating system Reduce Motion preference
- Ripple requires one valid local fallback image
- Directional mode requires a static WebP atlas whose columns × rows equals 8, 16 or 32
Import says the package is unsafe or damaged
The importer rejects a mismatch rather than silently discarding it. Re-export from the current Studio and keep manifest.json, theme.json, declared target files and hashes together.
- Do not add files manually after export
- Check file extension and media signature
- Reject remote URLs, scripts, raw CSS, HTML, SVG and path traversal
- Use the package for the application and client version recorded in its manifest
An update broke the theme
A client update can change internal surfaces even when the product still launches. Treat the new build as pending until representative screens, fallbacks and restore behavior are verified.
- Stop the old adapter
- Restore native appearance
- Record the exact new build and the failing screen
- Wait for a compatibility record instead of editing the signed app bundle
Troubleshooting questions
Why does my Codex background disappear after an update?
The adapter was verified against an exact client surface. A new build may change that surface, so stop the old adapter and wait until the new build is verified.
Why does ripple show only a still image?
Reduced Motion may be enabled, or no valid fallback image is attached. Ripple is intentionally static under Reduced Motion.
Why does a directional atlas show the wrong frame?
Check the direction count, columns, rows, first-direction angle, idle frame and origin. Columns multiplied by rows must equal the selected frame count.
Why is my WebP atlas rejected?
It must be a static WebP no larger than 32 MiB, 32 megapixels or 16,384 pixels per side, with evenly divisible grid cells.
Why is a .cctheme package rejected after I edited the ZIP?
Every declared file has an integrity hash. Adding, removing or changing a file without rebuilding the manifest makes the archive inconsistent.
Will restore delete my chats?
No. Restore removes CC Theme appearance and connection state; it does not delete or recover product data.