Troubleshooting

Browser Storage on File URLs

The generated site is static and can be opened directly from disk. Some browsers restrict localStorage on file:// URLs, which can affect theme state and media volume/mute persistence.

If behavior seems inconsistent, serve the output folder locally:

cd path/to/site
python -m http.server 8000

Then visit:

http://localhost:8000

Symlink or Hard-Link Failure

During media staging, cr4te tries to create symbolic links first and hard links second. If neither works, the build aborts instead of copying media files.

Common fixes:

• Enable symlink creation privileges.
• On Windows, enable Developer Mode or run from a shell with the needed rights.
• Put input and output on the same filesystem so hard links can be used.

Output Folder Already Exists

If the output folder exists, cr4te asks before clearing it.

Use --force to skip confirmation:

cr4te build -i path/to/Creators -o path/to/site --force

By default, existing thumbnails are preserved. Use --clean to delete thumbnails too:

cr4te build -i path/to/Creators -o path/to/site --clean --force

Custom Theme Build Aborts

A path supplied with --themes-dir must exist and must be a directory. cr4te checks it before changing metadata or output files.

Theme CSS files must be placed directly inside that folder, use portable lowercase slug filenames, and define the matching .theme-<slug> selector.

Invalid theme files are reported and skipped during a normal build. With --strict, the first invalid or duplicate theme file aborts the build.

See Custom Themes for examples.

Invalid Metadata

cr4te rejects invalid JSON, non-object metadata files, unknown fields, invalid dates, and missing path references.

Default best-effort mode reports issues and skips invalid entries where possible:

• Invalid creator metadata skips that creator.
• Invalid project metadata skips that project only.

Use strict mode when you want the build to fail immediately:

cr4te build -i path/to/Creators -o path/to/site --strict

Missing Portrait or Cover

If a configured portrait or cover path is set but missing, it is a metadata issue.

If no path is configured, cr4te tries to find a suitable image by configured basename. If none is found, it uses generated default thumbnails where needed.

Search Does Not Match Expected Values

Project facet values only participate in search if the resolved field config marks them as searchable, clickable, or tags.

Check:

cr4te print-config --domain music

Then inspect site_rendering.project_metadata.fields.

Media Does Not Appear

Check:

• The extension is supported.
• The file is within media_rules.max_search_depth.
• No folder or file path part starts with the configured exclude prefix.
• The file is not hidden.
• Image sampling has not excluded it.

Missing media and unreadable text or gallery images discovered during rendering are omitted from generated pages and reported as asset issues in the final build summary. Failed portrait and cover thumbnails use generated defaults instead.

Optional inspection failures, such as an unreadable audio duration, are reported as warnings and use a safe fallback.

Clean Metadata Carefully

clean-json deletes creator and project metadata files.

Preview first:

cr4te clean-json -i path/to/Creators --dry-run

Actually delete:

cr4te clean-json -i path/to/Creators --force