Diagnostic Codes

All diagnostics are written to stderr in the format:

[E006] ToString | Color @ include/color.h
       <detail message>

The fields after the code are: rule name, entity name, source path, detail. Any of the trailing fields can be empty.

Error codes

Code	Trigger	Resolution
E001	Rules directory not found	Check the path passed to -r.
E002	version: in the rule config is not 1	Set version: 1 or upgrade the codegen binary.
E003	transform.luau or preamble.luau not found in the rule directory	Add the missing handler/preamble.
E004	Grouping script returned a map missing one or more entity registryIds	Ensure every entity passed in is keyed in the returned map. The affected entity is skipped; the run continues.
E005	A path returned by grouping resolves outside the project root (CWD)	Use a path that stays under the working directory. The affected entity is skipped.
E006	Handler script raised a Lua error or an internal LuaU error occurred	See the detail line for the script line and reason. Internal errors are fatal (exit 2).
E007	Preamble script raised an error	The whole run aborts with exit 1. Fix the preamble before re-running.
E008	Grouping script raised an error or returned invalid JSON	The affected rule’s grouping is skipped (entities keep their default 1:1 path).
E009	Handler returned something that wasn’t json.encode({...})	Wrap the return in json.encode({...}).
E010	http.get(url) called with a URL whose host is not on permissions.http.allowlist	Add the host (example.com) or a wildcard (*.example.com) to the allowlist, or stop calling http.get for that URL.
E011	The --input path doesn’t exist	Check the path passed to -i.
E012	Output directory could not be created or output file is not writable	Check filesystem permissions and free space.
E013	--use-workspace path doesn’t exist	Check --workspace-dir (or the CWD when omitted).
E014	--use-workspace could not load the build-system config	See the detail line; usually a malformed codexx.workspace.yaml or unparseable CMake file-api reply.
E015	Rule config schema/shape error: unknown output.language, malformed permissions.http.allowlist / permissions.env.os_allowlist, extends: target missing, or extends: chain too deep	Fix the offending field in config.yaml (see detail line for which one).
E016	Rule config YAML parse failure	The detail line carries the YAML parser error. Fix the syntax in config.yaml.
E017	Engine init failure (LuaU environment could not be created)	Fatal (exit 2). Indicates an internal bug — file an issue with the detail line.
E018	Source analysis pipeline failed before any rule fired	Check the input headers parse cleanly with ast_dump.
E019	Two or more rules’ default output paths collide	Set outputNameTemplate or a grouping.luau to disambiguate.
E101	License invalid key (no signed token, malformed activation key)	Activate the component in codexx_dtdk_manager.
E102	Feature requires a higher tier (e.g. --dry-run TUI viewer is Professional+)	See Tiers & Pricing.
E103	Cached license token failed signature, machine-mismatch, expired, suspended, or corrupt	Re-activate the component in codexx_dtdk_manager.

Warning codes

Code	Trigger	Notes
W001	--use-workspace is set but the input has no entry in the loaded build-system config	Includes/defines won’t be auto-resolved for this input.
W002	A -D NAME=VALUE on the CLI overrides a workspace define of the same name	The CLI value wins; the warning is informational.
W003	An entity’s anchor is not present in its source header (or the anchor references an unknown entity)	The .g.cpp is still written; only the inline forward-declaration injection is skipped.
W004	Inline-edit file I/O issue (cannot open source for read, cannot write the temp file, or rename failed)	The inline edit for the affected file is skipped; the .g.cpp itself is unaffected.
W005	Unknown node_kind entry in config.yaml	The unknown entry is dropped; remaining node_kinds are honoured.
W006	Unsupported config feature referenced (e.g. permissions.registry)	The entry is ignored; the rule otherwise loads normally.

Exit codes

Code	Meaning
0	Success — all entities processed and all files written (or the dry-run preview completed).
1	Recoverable failure — license error, bad CLI, missing input, rule load failure, preamble failure, etc.
2	Fatal — handler internal error or LuaU environment creation failure.