Diagnostic codes

Each problem that archangel shows has a code, such as may-import or selector-empty. The code is in the first line of the problem: error[may-import].

• Run archangel docs <code> to see what a code means, an example, and what to do.
• Each code has a page on this site with the same text.

A rule violation exits with code 1. A config problem that stops the check exits with code 2. Some config problems, such as a group that finds no file, do not stop the check. They exit with code 1, because archangel can still check the other rules.

Rule violations

The code broke a rule of the config. The check fails with exit code 1.

Code	What it means
may-import	A file of a row of an import table imports something that its row does not list.
every-file-has-a-kind	A file in the `files` of an import table has no row in that table.
layers	An import goes from one part of a layers rule to a part earlier in its list.
isolate	A file in one instance of a part imports a file in a different instance of the same part, such as one feature importing another.
entry	Code outside an instance of a part imports a file inside it that is not one of the instance's entry files. A sibling instance counts as outside.
may-not-import	A file in the `files` of a `mayNotImport` rule imports a file or package on the rule's other side, directly or, for a transitive rule, through a chain of imports.
may-only-import	A file in the `files` of a `mayOnlyImport` rule imports a file or package that is neither on the rule's list nor in those files. When `files` is a part with a capture, only the files of the same instance count as those files.
may-only-be-imported-by	A file imports a file in the `files` of a `mayOnlyBeImportedBy` rule, and the importing file is neither on the rule's list nor in those files. A file in no part counts as outside the list.
no-cycles	A group of files import each other, so each can reach the others. The diagnostic lists every file in the group and shows its shortest cycle.
must-not-exist	A file is in the `files` of a `mustNotExist` rule, such as a file in no part or in a reserved folder.
must-be-named	A file or folder in a `mustBeNamed` rule has a name that is not in the rule's style, or a full name that does not match the rule's name pattern. For a rule with a list, the name matches no entry in the list.
must-contain	An instance of a part, or a folder, in a `mustContain` rule has no file that matches the rule's pattern.
must-export	A file in a `mustExport` rule exports no name that matches the rule's name pattern.
may-not-export	A file in a `mayNotExport` rule has an export of the kind the rule refuses: a default export, an `export *` or `export * as`, or a named export whose name matches the rule's pattern.
must-only-re-export	A file in a `mustOnlyReExport` rule has a top-level statement of its own: a declaration, a type included, or code that runs. It may hold only imports, exports from other files, directives, and `export { … }` of names it imported.
plugin	A file breaks a rule whose condition a plugin defines, such as `team/one-store-per-entity`. The plugin's condition wrote the message.

Config problems

The config has an error, or a rule in it can never find a problem.

Code	What it means
config-missing	Archangel found no config in the current folder or any folder above it.
config-needs-node	The config is TypeScript or JavaScript, and Node 22.18 or later is not on the search path.
config-load-failed	The config's code threw while it loaded, has no default export, or uses TypeScript that Node cannot strip, such as an enum.
config-invalid	The config has a field archangel does not know, a value of the wrong type, or text that is not valid JSON. The diagnostic names the field, such as `rules[0].reasn`.
pattern-invalid	A pattern has an empty folder name, a `**` that is not a whole folder name, a capture without a name, or the same capture name twice.
rule-unknown-element	A rule or a group names a part, a group or an externals set that the config does not declare. A string without a `/` or a `*` is a name, not a path pattern. The message lists the declared names.
rule-needs-capture	An isolate rule names a part whose pattern captures nothing, so it has only one instance.
rule-name-duplicate	Two rules have the same name, often the default name of two rules about the same files, such as `mayNotImport(entity, react)`. Exceptions and the baseline refer to rules by name, so each needs its own.
part-overlap	A file is in two of the config's own parts. A file can be in one part at most, so a rule about parts cannot know which part judges the file.
element-empty	A part or an externals set matches nothing, so no rule about it can fire. For a part, no file matches its patterns. For an externals set, no import uses its packages and no package manifest lists them.
selector-empty	A group that the config declares, a path pattern written inline in a rule, or the `folders` of a folder rule matches nothing, so no rule about it can fire.
preset-empty	A preset the config extends matches no file with any of its parts, so none of its rules can fire.
table-empty	A table has no row, or its rows together have no file, so the table checks nothing.
table-row-overlap	A file in a table's files is in two rows of that table. Each of the two rows judges the file.

Repository problems

Archangel could not read a file, an import or a setting of the repository.

Code	What it means
file-unreadable	Archangel cannot open a folder or a file, or a source file is not UTF-8 or UTF-16 text.
parse-failed	A source file has syntax errors, uses Flow syntax, or is larger than the parser accepts. Archangel uses none of its imports, because a parser that recovers from errors can invent or lose imports.
import-unresolved	Archangel cannot find the file or package that an import names. The message says why in plain words.
resolution-file-invalid	A tsconfig or package manifest that resolution needs is not valid: it does not parse, cannot be read, or extends a package that is not installed. Archangel reports it once, not once per import.
ignore-line-invalid	A line of the config's `ignore` list is not valid `.gitignore` syntax.
exports-unknown	A `mustExport` rule needs the names a file exports, and the file passes names on through an `export *` from a package or from a specifier that does not resolve, so archangel cannot know them.

Exceptions and the baseline

An exception comment or the baseline file has a problem.

Code	What it means
exception-without-reason	An `archangel-allow` comment gives no reason after the colon, so it permits nothing.
exception-unknown-rule	An `archangel-allow` comment names a rule that the config does not have. The message lists the rules that exist.
exception-unused	An `archangel-allow` comment permits nothing, because the import after it does not break the rule it names. The import after it is the one whose specifier is on the next line, or whose statement starts on the next line. Exceptions go away when the code is fixed.
baseline-invalid	The baseline file, `archangel.baseline.json`, does not parse.
baseline-stale	A baseline entry permits more violations than the code has, because they were fixed, or it names a rule that no longer exists. A check never rewrites the baseline.

Examples and plugins

A rule is not proved, an example failed, or a plugin did not run.

Code	What it means
rule-unproven	A rule has no rejected example, so nothing proves that it can find a violation.
example-proves-nothing	An accepted example passed, but its rule never looked at it, so it proves nothing. An import rule looks at imports, a rule about files at files, a folder rule at folders, a `mustContain` rule on a part at its instances, and a plugin rule at the files of its view. The message says which one the rule never looked at.
example-failed	A rule did not judge an example as the example says: it accepted a rejected example, or rejected an accepted one. When another rule rejected the example instead, the message names it.
plugin-failed	A plugin could not give its condition's result: the condition threw, it reported a file that was not in its view, or the plugin's Node process stopped.