Diagnostics
Ramonda reports the common mistakes below at runtime, in development only. Every message is wrapped
in if (__DEV__), so a production build ships none of them. Nearly every check is stripped with
its message; the exception is named where it applies (RML009), because a guard that ran only in
development would protect the one build that was never exposed to a request.
Every code has a page of its own, at /reference/diagnostics/ and the code in lower case — and
npx ramonda-check explain RMD020 prints the same page for the version you have installed, with no
network.
Arrived with a symptom rather than a code? Something is wrong lists what you can see and sends each one here.
They exist because these mistakes are silent. Almost every bug this framework has had produced a wrong result rather than an error: state landing on the wrong row, a click doing nothing, a subtree rendering into nodes nobody can see. None of them threw. A diagnostic is the framework saying the thing a stack trace never would.
Most are deduplicated by cause, so a mistake in a list of a thousand rows is reported once. Whether
to dedupe is the reporting package's call, and it follows from what the fault depends on: a core
diagnostic fires from the render path for a fixed piece of code, so the second report carries nothing
new, while an RML miss depends on the data — the same line can miss for one record and land for the
next, and collapsing those would hide the case that matters.
Error or warning says what is at stake, not how bad the code looks. An error means the end result is wrong — something renders the wrong thing, loses state, never becomes interactive, or hands you a value that is not what you asked for; the devtools panel raises its alert for these. A warning means the result is the same and the app just did more work to get there: a wasted render, a refetch, a listener re-attached.
The prefix says which package reported it: RMD is @ramonda/core, RMQ is @ramonda/query,
RMF is @ramonda/form, RML is @ramonda/lens. They are listed apart below, because a reader who
hits RMQ001 wants the query codes together and not one of them wedged between two core ones.
A code is stable forever and never reused. When a check is removed, its section stays and says
retired — a reader who hits an old message in an old build still lands somewhere.
Capturing them
A diagnostic is also a record, so a devtools panel, a test, or a log collector can group and filter reports instead of parsing prose. A collector installs one function, and a reporting package finds it with no dependency on anything:
Every prefix arrives this way — RMD, RML, RMQ and RMF.
interface RamondaDiagnostic {
/** Stable forever. The prefix says which package raised it. */
code: string;
/** Who emitted it — `"ramonda/lens"`. OpenTelemetry calls this `InstrumentationScope.name`. */
scope: string;
/** Mapping to OpenTelemetry SeverityNumber 5 · 9 · 13 · 17. */
severity: "debug" | "info" | "warn" | "error";
/** One sentence, human first. Interpolated values are fine — grouping is by `code`. */
message: string;
/** What to do instead. Always present for an `error`. */
fix?: string;
/** The values the message interpolated, structured. What a collector queries. */
data?: Record<string, unknown>;
/** Epoch millis. Sortable, comparable, locale-free. */
time: number;
/** Identifies the SOURCE of a fault. Absent means "never deduplicate this". */
dedupKey?: string;
/** The fault was also thrown where it happened, so whoever ran the code already met it. */
thrown?: true;
}
declare global {
var __RAMONDA_DIAGNOSTICS__: ((record: RamondaDiagnostic) => void) | undefined;
}
globalThis.__RAMONDA_DIAGNOSTICS__ = (record) => {
if (record.severity === "error") myCollector.alert(record);
};
If you have @ramonda/devtools, subscribe instead of assigning. The sink is one function, so an
assignment replaces whoever was there — which is normally the panel's own bridge, and it then quietly
stops filling. installDiagnostics shares one sink between any number of subscribers and hands back
the uninstall:
import { installDiagnostics } from "@ramonda/devtools";
const stop = installDiagnostics((record) => myCollector.alert(record));
A subscriber sees every prefix. The panel's LOGS tab is the one place that differs: RMD rows reach
it through core's own log channel, so the bridge does not carry them there a second time.
The assignment above is the protocol-level form, for a package that will not take a dependency to report a warning. Write it when that is the situation, and chain what was already there:
const previous = globalThis.__RAMONDA_DIAGNOSTICS__;
globalThis.__RAMONDA_DIAGNOSTICS__ = (record) => {
previous?.(record);
myCollector.alert(record);
};
Four rules make it work across packages that share no code:
globalThis, not an event onwindow. The same line runs in the browser, in Node, in a worker and during a server render. A reporting package needs no dependency and no DOM.- A collector is optional. With nothing installed, the call is one property read and the message still goes to the console. Installing a sink adds a consumer; it does not silence the console.
- Read tolerantly. Ignore fields you do not know, and assume only
code,scope,severity,messageandtime. That is what lets the record grow without a version on every one of them. dataholds values, not live objects. A collector keeps a bounded history, and a record holding a component or a DOM node would keep it alive for as long as that history does.
The field names line up with OpenTelemetry's log data model, so bridging to a collector is a rename rather than a redesign. Anything can emit into this channel — the contract is the shape above and the name of the sink, not a package to depend on.
On the server the sink is process-wide, so a collector sees every concurrent request at once; there is no per-request attribution in the record.
Core — RMD
RMD001— State written duringrender()RMD002— Duplicate key in a child listRMD003— Context consumed without a provider above itRMD004— Props mutated by the receiving componentRMD005— Array in state mutated in placeRMD006— Timer still running after unmountRMD007— Server and client rendered different outputRMD008— State changed after the component was unmountedRMD009— Update loop: a component never stopped re-renderingRMD011— A function was used as a JSX tagRMD012— retiredRMD013— A list item produced nothingRMD014— retiredRMD015— A hook's props assigned by the hook that received themRMD016— A component updated while its element is not in the documentRMD017— A deferred hydration never resumedRMD018— State written during a@computeRMD019— State set to a value that cannot be serializedRMD020—render()produced a different value the second timeRMD021— A random number was read while a value was being derivedRMD022— A hook's props callback built a new value for the same contentsRMD023— Children built from an array need a keyRMD024— A@computerecomputes without its answer changingRMD025— Per-request data read in the browserRMD027— A props callback reads a value that is not reactiveRMD028— An element the HTML parser is not allowed to keep hereRMD029— A boolean attribute given the string "false"RMD030— State written during[INSPECT]()RMD031— A list item that is not an elementRMD032— More than one@catchErroron a componentRMD026— retiredRMD033— State that cannot cross to the clientRMD034— State written during create or mount is not carried to the clientRMD035— The client's hook tree does not match the server'sRMD036— The state blob could not be readRMD037— An object among JSX children that is not markupRMD038— A@watchPropselector threwRMD039—classwhereclassNamewas meantRMD040— More than one@ShouldUpdateOnPropsChangeon one classRMD043— A<meta>with nothing to identify itRMD044— An unknown element type in JSXRMD046— More than one@StablePropson one classRMD047— A@memoizedmember was given an argument it cannot key onRMD048— Object in state changed in placeRMD049— Two lazy functions with the same sourceRMD050— A decorator whose effect this member already has
Forms — RMF
RMF001— a field was assigned toRMF002— the list members were used on a field that is not a listRMF003—onSubmitthrewRMF004— the schema's validation rejectedRMF005— a field edited through a control that hands back another kind
Query — RMQ
Immutable updates — RML
RML001— a path that could not be reachedRML002— a path into aMap,SetorDateRML003— an array hop on something that is not an arrayRML004— an index outside the arrayRML005— a predicate that matched nothingRML006— an operation that needs a different kind of valueRML007— nothing to removeRML008— a fork branch that returned nothingRML009— a key a write is refused forRML010— a chain written through twiceRML011—remove()at the rootRMD051— A list row cannot be told apart from its siblingsRMD052— A component among JSX children, where an element was meantRMD053— The request was read with no request scope installedRMD054— A post-commit callback threw, and the failure was swallowedRMD055— A hook's props passed as a plain objectRMD056— One context provided twice by the same componentRMD057— A context consumed above the provider on the same componentRMD058— The request blob could not be readRMD059— An async lifecycle rejectedRMD060— render() is asyncRMD061— A ref was built while a value was being derivedRMD062— A field read its model while a commit ran
Next
- Checking your app — the same faults proved from your source, before any of these can be reported.
- Rules — every check that runs there, one page each.
- Reference — the other pages you come back to rather than read once.