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

Build failed? 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.ts

registry-build build --config ./apps/docs/registry-build.config.ts

If the package is installed in a workspace app, run the script from that app rather than the repo root.

Source path does not exist

No files found for entry ...

Unknown registry item type

TS config file does not load outside Bun

Warm builds still rewrite files

changed-only still does more work than expected

Generated component-index imports point at the wrong package path

Debug commands

registry-build build --verbose
registry-build build --json --silent
registry-build build --config ./registry-build.config.ts

registry-build build --verbose
registry-build build --json --silent
registry-build build --config ./registry-build.config.ts

To compare cache behavior, temporarily disable incremental mode in config and run once.

Debugging rule

Don't debug by editing generated output. Debug the inputs: config, source files, mappings, and extensions. Generated outputs are a consequence, not a source of truth.