Troubleshooting
Common registry-build failure modes and the fastest way to debug each one.
Most failures fall into one of four buckets: config discovery, path resolution, source discovery, or output/caching expectations.
Fast triage
When a build fails, check in this order:
- Was the right config discovered?
- Are all config-relative paths declared from the config file's point of view?
- Do the declared registry item types match the source and mapping keys?
- Did the expected source files actually exist under the declared source root?
- Is a cache expectation hiding a real content change?
Common symptoms
Config not found
Run the CLI from the consumer root or pass --config / --cwd explicitly.
registry-build build --config ./apps/docs/registry-build.config.tsregistry-build build --config ./apps/docs/registry-build.config.tsIf the package is installed in a workspace app, prefer running the script from that app instead of from the repo root.
Source path does not exist
This almost always means the path was written as if it were relative to the current working directory instead of relative to the config file that declared it.
Fix the path in config, not in the caller shell.
No files found for entry ...
Check sources[type].path, entry.root_folder, sources[type].glob, and sources[type].ignore.
Also verify whether the source should be indexStrategy: 'item' or indexStrategy: 'file'.
Unknown registry item type
The same registry item type namespace must be declared consistently across schema.itemTypes, sources, targetPaths, packageMappings, and each RegistryEntry.type.
Everything must still satisfy registry:${string}.
TS config file does not load outside Bun
Use JSON configs if you need the most portable runtime path. TS config loading depends on the runtime's ability to import TS or the provided loader fallback. If you need maximum portability across environments, keep the config declarative and move custom logic into plain JS/JSON-safe shapes where possible.
Warm builds still rewrite files
This usually means the generated content is changing, not the cache. Check for unstable ordering, custom generators with non-deterministic output, timestamps or environment-specific strings, and changes in rewritten imports or stripped variables.
changed-only still does more work than expected
Make the changed paths more specific. File-indexed sources can narrow rebuild work more accurately than folder-indexed sources. Passing a whole source root will still mark many entries as affected.
Generated component-index imports point at the wrong package path
Check importMappings.packageMappings first. If the generated import path still is not what you need, provide a custom generator through componentIndex or componentIndexExtension().
Debug commands
registry-build build --verbose
registry-build build --json --silent
registry-build build --config ./registry-build.config.tsregistry-build build --verbose
registry-build build --json --silent
registry-build build --config ./registry-build.config.tsIf you need to compare cache behavior, temporarily disable incremental mode in config and rerun once.
Debugging rule
Do not debug this package by editing generated output first. Debug the inputs: config, source files, mappings, and extensions. The generated outputs should be treated as a consequence, not as the source of truth.