Docs · Diagnostic codes

◍ Diagnostic codes

Every diagnostic oam reports carries a stable OAM-* code. The prefix says which subsystem raised it; the number is stable across releases so you can match on it.

Where codes come from

Under --json, oam writes one JSON object per line to stderr, each carrying code and a docs link back to this page. Without --json the same diagnostic is pretty-printed as error[CODE]: message (file:line:col). Both come from one object, so the two forms can never disagree. See ODIF for the envelope.

oam also explains codes without a network. Register its MCP server (claude mcp add oam -- oam mcp) and the explain tool answers from a table compiled into the binary.

The families

• OAM-PARSE* — parsing and transforming your source.
• OAM-MOD* — resolving and loading modules.
• OAM-RT* — the running program.
• OAM-TS* — type checking.
• OAM-TEST* — the test runner.
• OAM-PKG* — oam install.
• OAM-NATIVE* — loading native addons. These arrive as the code property of a thrown Error, not as an ODIF diagnostic.

Parsing

OAM-PARSE0001 error

A parse error from oxc. The source is not syntactically valid JavaScript or TypeScript at the span given. Nothing downstream can run until it parses.

OAM-PARSE0002 error

The source parsed, but the TypeScript-to-JavaScript transform failed on it — an unsupported combination of syntax rather than a typo. The message names what the transform refused.

Modules

OAM-MOD0001 error

A relative import resolved to nothing. The message lists every candidate path oam tried, in order. Create the file, or fix the specifier — a missing extension is the usual cause.

OAM-MOD0002 error

A package was not found in any node_modules directory above the importing file, or the entry point it named does not exist. Install it, or check that the version installed has the file the specifier asks for.

OAM-MOD0003 error

This module cannot be executed as a program: a .json file used as the entry (import it from a script instead — JSON imports work), an import attribute type oam does not support, or an unknown extension. .cjs and .cts run through CommonJS interop; .tsx and .jsx run through the JSX automatic runtime.

OAM-MOD0004 error

The specifier itself is malformed — bare . or .., or backslash separators. Write ./name or ../name, with forward slashes on every platform.

OAM-MOD0005 retired

No longer emitted. CommonJS entries execute through interop rather than being refused. If you are seeing it, an old oam is running; upgrade.

OAM-MOD0006 error

A recognised Node builtin that this build does not implement. The message names the module. The set grows release to release, so the message and the conformance scorecard are the current answer — not any list written down elsewhere.

OAM-MOD0007 error

The package exists, but its exports map does not export the subpath you asked for. Node reports the same condition as ERR_PACKAGE_PATH_NOT_EXPORTED. Check the package's documented entry points.

OAM-MOD0008 warning

A tsconfig.json has an extends naming a package (@tsconfig/node20 and friends), which oam does not resolve. The declaring file's own compilerOptions still apply; only what it would have inherited — paths, JSX settings — is missing. Inline those options, or extend a relative path.

OAM-MOD0009 warning

A tsconfig.json could not be used: it is not valid JSONC, it could not be read, or its extends chain is deeper than eight levels (which is how a cycle presents). Its compilerOptions are ignored until it parses. oam check reports the exact syntax error.

Runtime

OAM-RT0001 error

A runtime error that is not one of the more specific codes below. Most often an uncaught exception raised on a path that does not use the Node-format report; also the engine's own hard limits, such as a source or a path too long to become a V8 string.

OAM-RT0002 error

The runtime could not read a file or start a subsystem — an I/O failure below your program rather than inside it. The message carries the path and the operating system's error.

OAM-RT0003 error

top-level await never settled. The program is waiting on a promise, and no timer, no pending I/O and nothing else remains that could ever settle it. That is a deadlock, not slowness, so oam reports it instead of hanging. Find the promise nothing resolves or rejects.

OAM-RT0004 error

Two unrelated conditions share this code today, so read the message:

• An unhandled promise rejection — a promise rejected with nothing attached to catch it, Node's ERR_UNHANDLED_REJECTION. Attach a .catch(), or await it inside a try.
• The inspector could not start — could not start inspector on <address>, usually because the port is already bound. See the inspector page.

OAM-RT0005 error

An uncaught exception, reported in Node's own format: the offending source line, a caret, the stack, then the error's own properties. The first stack frame is the throw site, and frames from a .ts file cite the line you wrote, not the transpiled one.

This is the one diagnostic oam does not wrap in error[CODE]:, because doing so would bury the stack and break the ^Error: line that tools grep for.

Type checking

OAM-TS<number> error or warning

A TypeScript diagnostic, passed through from tsgo with oam's spans and tsgo's own number: OAM-TS2345 is TypeScript's TS2345. There are thousands of these and they are TypeScript's to define, so this page does not restate them — search the number in the TypeScript documentation, and treat the message text as authoritative.

oam's own type-check codes are the zero-padded ones below. That is how to tell them apart: a leading zero means oam raised it, no leading zero means TypeScript did.

OAM-TS0000 error

tsgo, the native TypeScript compiler oam checks with, is not installed or not on PATH. Install it with npm i -g @typescript/native-preview, or point oam at a binary with the OAM_TSGO environment variable. Your program still runs; only checking is unavailable.

OAM-TS0002 error

oam could not launch tsgo, or launched something that is not tsgo — the message includes what --version printed and what was expected (a major version of 7 or above, from @typescript/native-preview). A tsc on PATH under the name oam resolved is the usual cause.

OAM-TS0003 error

oam check found no tsconfig.json walking up from the target. Point it at a .ts file directly, or add a tsconfig.json to the project.

OAM-TS0004 error

tsgo exited abnormally without producing diagnostics; its raw output is in the message. Usually a tsgo crash or bad flags, not a problem in your code.

OAM-TS0005 warning

The concurrent type check did not finish before your program exited, so there are no type results for this run. That is the design — oam run never blocks on the checker — and the message says which case you are in: a project with a tsconfig.json is warming its daemon and will be instant next run; a single file has no daemon, so run oam check <file> for results. OAM_CHECK_WAIT_MS lengthens the wait if you would rather pay for it.

OAM-TS0006 error

tsgo ran past its timeout and its process tree was killed. The message carries the timeout and the command. OAM_TSGO_TIMEOUT_MS raises it for a genuinely large project.

OAM-TS0007 error

The tsgo run was cancelled before it finished — the work it was doing is no longer wanted, typically because the run that asked for it ended.

Test runner

OAM-TEST0000 info or error

The machine-readable summary of a oam test --json run: counts of passed, failed, skipped, todo and file-level errors, plus the elapsed time. Severity is info when everything passed and error when anything did not, so a consumer can gate on the severity alone.

OAM-TEST0001 error

One test failed. The message is FAIL <full test name>: <assertion message> and the span points at the file. Re-run just that test with oam test -t '<name>'.

OAM-TEST0003 error

The run itself failed outside any test — the runner could not start, did not return results, or the results failed to serialize. No individual result is trustworthy until this is fixed; look for a file-level throw before any test registered.

Install

OAM-PKG0000 info

The summary of a successful oam install --json: how many packages were installed and how long it took. Informational, emitted even when nothing failed.

OAM-PKG0001 error

The lockfile could not be read or parsed. If it is missing, run npm install once to generate package-lock.json — oam installs from the lockfile and does not write one.

OAM-PKG0002 error

Unsupported lockfileVersion. oam reads version 3; regenerate with npm 7 or later.

OAM-PKG0003 error

The installer could not build the machinery it needs — its async runtime or its HTTP client. This is a local environment failure, not a problem with your dependency tree.

OAM-PKG0004 error

One package failed to install: failed to install <key> plus the underlying cause (the download, the SRI integrity check, or extraction). The key is the lockfile path of the package, so a duplicated dependency at two versions is unambiguous.

OAM-PKG0005 warning

Bin shims could not be created — the .bin directory could not be made, or a package directory could not be canonicalized. The packages are installed; commands they provide are not on node_modules/.bin. A warning, so it does not fail the install.

OAM-PKG0006 error

only --frozen-lockfile mode is supported in this release. oam install is the npm ci equivalent: it installs exactly what the lockfile says and never changes it.

OAM-PKG0007 warning

A package's lifecycle scripts were skipped. The message names the package, its version and which scripts — skipping arbitrary code from a dependency is the default, not a failure. Allow one with oam trust add <package>. The same code covers the blanket skip when OAM_IGNORE_SCRIPTS is set.

OAM-PKG0008 warning

oam install --precompile could not pre-transpile some files in a package. The message names the package and the first few failures. Nothing is broken: those files transpile on first use, as they would without --precompile.

OAM-PKG0009 error

A lifecycle script you had trusted ran and failed. The message names the package and the phase. The install is partial: that package is on disk but its build step did not complete.

Native addons

These two are the code property of a thrown Error, not ODIF diagnostics, so they reach your program as a catchable exception at require() time. That is deliberate: the try { require(native) } catch { fall back to JS } pattern has to keep working.

OAM-NATIVE0001 thrown

Native .node addons are disabled by default, because an addon built against Node can deadlock the operating system's loader when opened inside oam — a hang before any oam code runs. Set OAM_ENABLE_NATIVE_ADDONS=1 to opt in to oam's N-API support, which is alpha.

OAM-NATIVE0002 thrown

This build of oam has no N-API support at all: it was compiled without the napi cargo feature. A distinct code from OAM-NATIVE0001 on purpose, so the message never suggests setting an environment variable that cannot help. Rebuild with the default features.