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

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.

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