Skip to main content

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:

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:

  1. Give the dependency types: install @types/* (declarations are picked up automatically) or declare a named env — Dependency types
  2. Mock what analysis cannot execute (fetch, native bindings) — Mocking
  3. 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.analysis include / exclude, then reload the window — Coexistence recipe
  • .ts / .tsx buffers 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:

  1. Declare it: @nudo:throws RangeError above the function — @nudo:throws
  2. Digest it: try/catch at the boundary, or refine the parameter so the throwing path narrows away
  3. Migration relief only: --ignore-throws, --entry-throws warning, or --profile adoption, persisted in package.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.