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 and reused when the source path, byte size, modified time, and thumbnail recipe still match. Use --clear-thumbnail-cache to remove cached thumbnails before rebuilding, especially if source files may have changed while preserving their timestamps:

cr4te build -i path/to/Creators -o path/to/site --clear-thumbnail-cache --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

To provide a named portrait or cover, add an image with the configured basename to the creator or project folder. cr4te prefers direct matches before searching subfolders. Portraits and covers appear in places where the corresponding detail-page image role is set to show or if_available, or where a card context such as the creator overview uses image cards.

If no portrait basename match is found, portrait_discovery: auto may select a portrait-oriented image. Creator overview image cards use generated defaults when no usable source image is available. Detail-page image roles set to show also use generated defaults when no usable source image is available; roles set to if_available omit the image instead. Cover discovery continues through its landscape and arbitrary-image fallbacks; card contexts may use generated defaults when no cover source is selected.

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 detail-page portrait and cover thumbnails use generated defaults for show roles and are omitted for if_available roles. Card and gallery contexts may use generated defaults where applicable.

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

Delete Metadata Carefully

delete-metadata deletes creator and project cr4te.json metadata files without affecting media files.

Preview first:

cr4te delete-metadata -i path/to/Creators --dry-run

Actually delete:

cr4te delete-metadata -i path/to/Creators --force