Troubleshooting
The questions that come up most in the first hour with Nudo — each answered in one breath, with a link to the full story. Nothing here matches? Every nudo:* code is listed in Diagnostics.
Why is my parameter any?
any means unconstrained — no contract and no call-site evidence yet. It is not an inference failure and not a bug: Nudo never invents obligations by scanning the function body (Limits). To narrow the parameter, give it evidence:
- a sidecar
*.nudo.jscontract or@nudo:contract— see nudo contract - a call site — real arguments narrow the signature (Quick Start, Call-Site Discovery)
any ≠ unknown: unknown is reserved for inference failure (Introduction).
Why does + return number | string?
export function scale(x) {
return x + 1;
}
export function formatName(first, last) {
return first + " " + last;
}
scale(5);
formatName("Ada", "Lovelace");
Run it with nudo check and the signatures block reads:
scale(x: any) => number | string throws TypeError
Honest JavaScript, not a bug: an unconstrained operand to + can drive numeric addition or string concatenation ("7" + 1), so both branches are kept instead of guessing. Constrain x — a contract or call-site evidence — and the union collapses to number (scale(x: number) => number). Full story: Language semantics · Quick Start.
What does unknown mean and how do I fix it?
unknown is inference failure (engine debt) — never the default display for unconstrained entry params (Limits). Fixes, best first:
- Give the dependency types: install
@types/*(declarations are picked up automatically) or declare a named env — Dependency types - Mock what analysis cannot execute (
fetch, native bindings) — Mocking - Prefer modeled constructs over the not-modeled list — Language semantics
VS Code (or another editor) shows nothing
The IDE analysis gate is nudo.analysis.mode, shipped default "exports": only files with export / sidecar / @nudo:* directives are analyzed (VS Code). Open a file that exports something. Still quiet? Check the gate:
- Monorepo: scope
package.json#nudo.analysisinclude/exclude, then reload the window — Coexistence recipe .ts/.tsxbuffers are intentionally not Nudo analysis targets by default
Why doesn't nudo test see my vitest suite?
nudo test is a case reporter — call@L / entry@L cases plus declared @nudo:case assertions — not a test runner; it never runs vitest and ignores test files unless you point it at them (CLI Reference):
nudo test lib/ --from test/
The harvesting pass executes the shape of each test file inside Nudo's evaluator (it / test / describe callbacks are invoked; the framework itself never runs) and injects every observed call as a synthetic case — Call-Site Discovery.
nudo check fails with nudo:entry-may-throw on an intentional throw
L2 requires entry/export functions not to carry undeclared, uncaptured throws — like Node exiting non-zero on an uncaught exception (L2 — entry throws). Fixes, best first:
- Declare it:
@nudo:throws RangeErrorabove the function —@nudo:throws - Digest it:
try/catchat the boundary, or refine the parameter so the throwing path narrows away - Migration relief only:
--ignore-throws,--entry-throws warning, or--profile adoption, persisted inpackage.json#nudo.check(CLI Reference)
Where did infer / types / interface / refine go?
Deleted in the CLI product-face cleanup — breaking, no compatibility layer (release history). The primary verbs are check / test / contract / export / health.
Current per-package notes: Releases.
Signatures print even on success — is that a bug?
No — that is the observation face. check prints signatures on success and failure; only the FAILED / issues block and the exit code (1 on any error-level diagnostic) tell you whether the gate passed (nudo check; output below quoted from Quick Start):
nudo check calc.js
FAILED
2 error · 0 warning · 0 info · 2 fn
signatures
scale(x: any) => number | string throws TypeError
formatName(first: any, last: any) => string throws TypeError
The Day-0 face fails the gate: an unconstrained + operand's ToPrimitive can throw TypeError (native Symbol coercion), so L2 flags both exports — constrain the params (a sidecar contract) or declare @nudo:throws TypeError.