Troubleshooting
What goes wrong in treflex apps, by symptom, and then every code the runtime reports.
Symptoms
- A hang: an action never ends, or a dispatch, receiver, tick or error boundary runs long after it should. The work is queued behind a hold. Either the holder waits on work that needs its own entity or one above it, which never ends, or a long wait holds when it should let others in.
action/long-holdnames the holder, what it waits on and what is queued (below). Make the wait point down, put it insideopen(...), or move the queued work onto a child entity (waits point down). A dialog nobody can answer is the same shape (a stuck dialog). - A button stays live while its click is queued, or a repeat runs twice. It is bound to a flag the action sets in its first step, and the click queued behind another hold, so the flag isn't set yet; a guard on the flag doesn't stop a repeat, which runs after the first has cleared it. Disable from
useInFlight, which counts queued work, and mark the actionleadingto drop a repeat (busy state, arrival marks). - An action finds its entity's fields changed after a wait it didn't open. An action on an entity above it wrote into the entity while this one held it; in development that reports
entity/written-while-held(below). Send the write to the entity as work,yield* start(applyEvent, doc, event)(writing into a child entity). - A blank page at load, while tests and typecheck pass. An import cycle reads an export before the export exists, such as a
const save = leading(function* ...)reached before its line runs. Vitest's module loader answersundefinedfor that read instead of throwing, so only a built bundle shows it. Keep one test that loads the production bundle (check the app loads), and mark actions with a statement after a declaration (marking a function). - A failure is reported twice. The app logs from the
failureevent and has noonError, so every failure nothing else takes is reported by the logger and again as an unhandled rejection. KeeponError: () => {}beside the logger (onError). - A receiver case doesn't fire. The receiver isn't registered, the entity isn't bound to it, the binding landed after the publish, a
publishToNearestwent to the wrong entities, or a test asserted before the receiver ran. Work through when a receiver doesn't fire. inFlightdoesn't count a receiver's work. A delivery counts as its matched case. A case that calls the action withyield*counts as itself, not as the action: write the case bare,"Content/Saved": refresh, so it counts asrefreshand asrefresh's work tags. Work on a child entity doesn't count for its parent (whatinFlightcounts).
Diags
A diag is the runtime telling you something about itself: a rule it refused, a mistake it caught, a cost it noticed. Each one goes to the console, console.warn or console.info by severity, and to runtime.on("diag", handler) as { severity, code, message, data? }. code is the stable name a tool matches on; message is for people and may change.
import type { IRuntime } from "treflex";
export function forwardDiags(runtime: IRuntime<object>, send: (code: string, data: unknown) => void): () => void {
return runtime.on("diag", (event) => {
if (event.severity === "warn") send(event.code, event.data);
});
}- A diag subscriber's own throw goes to the console only.
- The diags of a restore's table load are held until
setuphas run, so a listenersetupattaches hears them (restart-and-records.md). state/view-writecomes from a view, which carries no runtime, so every live runtime's listeners hear it.- "Once per" below means once for the runtime's life, unless an entry says what clears it.
- A development build is defined in
runtime.md.
What an action throws is not a diag: it is a failure, heard through the failure event (failure.md).
Every code
Actions
action/large-read-copy
One read in an action copied more than 10,000 objects and arrays. A read in an action is a frozen copy of everything it returns; a transient and pendingAsks are exempt. An external read copies the whole value, inside a select too. Once per action name, and per key for an external read. Data: { actionName, type, copied }, type being the read, and key for an external read. Do: read only what the action needs, with a narrow select; for an external read, provide what the action needs under a narrower key.
action/long-hold
An action holding its entity has had work queued behind it for over a second, counted from when work first queued behind this hold, or from the hold's start if work was already waiting when it began. Checked every second while that lasts, and reported once per hold for each set of effect types the holder is found waiting on, so a loop around one wait reports once; a new hold reports afresh. Data: { entityId, holder, holderId, waitingOn, queued }, the queued work by name. Do: if other work should run during the wait, write yield* open(...) around it; if the queued work belongs to a part with a life of its own, make that part a child entity; if the wait is on work queued behind the holder's own hold, it never ends, since waits point down (actions.md).
The symptom: a dispatch, a receiver, a timer tick or an error boundary's delivery runs later than expected, after another action on the same entity finished.
action/name-collision
A second function was given a durable name another already had, in a production build, where it means two modules claim one name; in a development build the mark throws instead, unless it comes from the same module, which is a hot reload. Both functions keep recording the name, so their records can't be told apart by it, and the name resolves to neither. The page's names are shared by every runtime on it, so every live runtime hears it, and a runtime created later hears the ones raised before it. Every such mark. Data: { name }. Do: give one of the two another name (actions.md).
action/refusal-loop
An action was refused 100 times running at its yields for writes that broke the tree rule, each step undone and the refusal thrown back in, with no step passing between, so the next refusal ended the action. Data: { actionName, branchId, error }, the refusal serialized. Do: a catch around a yield that retries the same writes meets the same refusal: rethrow it, or change the writes.
action/refusal-swallowed
An action caught a refusal its own code was refused with, and ended without rethrowing it, so the broken rule went unheard. Judged when the action and all its branches have ended. Once per action run. Data: { actionName, actionId, entityId, refusal, count }: the first refusal serialized, and how many there were. Do: if (isRefusal(error)) throw error; in a catch that can meet one (failure.md).
action/unnamed
A runtime with requireNames ran an action that would be saved and has no durable name, in a production build; a development build refuses it with UnnamedActionError instead. The action runs, and its records and any snapshot entry carry Name: null, so a later restore can say only which entity it ran on. Once per function in each runtime. Data: { label }, the function's own name or null. Do: name it with named(action, "Feature/Action") in its module, or run npx treflex-eslint name which names the unnamed actions it can find in the project (runtime.md).
action/unrouted-throw
An action's code threw, the runtime caught it, and nothing routes it: a close throw after the one failure the action routes, a close throw in an action that ended another way, or what stopped work on an entity that left the tree threw on its way out. Once per throw. The same throw reaches the failure event with Taken: false. Data: { actionName, entityId, close, error }, the error serialized. A routed failure nothing took raises no diag: it is an unhandled rejection already.
entity/written-while-held
An action wrote into an entity another action holds, so the holder can find what it read changed after its wait. Once per pair of writer and holder functions. Data: { writer, holder, entityId, path, slot? }, slot naming the transient when the write went into one. Do: send the write to the entity as work, with yield* start(...) (actions.md).
cancel/finally-yield
A finally yielded while its generator was being closed. Nothing can run an effect during a close, so the rest of that finally block was skipped; outer ones still run. Every such yield. Data: { actionName, branchId, yieldedType }. Do: keep finally to synchronous writes; effectful cleanup on the stop path belongs to something that survives the stop (fibers.md). The treflex/no-yield-in-finally lint rule reports it before it runs.
cancel/finally-yield-limit
A close yielded more than 100 times, so the generator was abandoned with the rest of its finally blocks unrun. Data: { actionName, branchId }.
Dispatch
dispatch/unresolved-entity
Two producers. runtime.dispatch, or a feature's action, named an $Id the tree doesn't hold: unknown, removed, component state whose component unmounted, or a root with no $Id. The dispatch rejects with EntityGoneError before the action starts. Once per $Id, cleared when that $Id next dispatches; the rejection recurs on every call. Data: { entityId, cause: "unresolved" }. Do: give the root a $Id; gate a view on a slot that holds nothing yet.
start named an entity the tree doesn't hold, so the action wasn't started and the starting action went on. Every time. Data: { entityId }. Do: start it once the entity is in state.
dispatch/node-mismatch
A dispatch's or a start's target was a node, and not the one the tree holds under its $Id. A dispatch rejects before the action starts; a start throws at its yield. Once per refused node and cause, until that node is accepted as a target again; dispatches by its $Id or with other nodes don't clear it. Data: { entityId, cause }. "superseded": the node was this tree's and has left it; read the entity from the tree again. "foreign": a copy or other plain value carrying the $Id, such as a spread or an action's returned value, or another runtime's node; dispatch by the $Id, or with the tree's own node.
Effects
effect/sync-returned-promise
A settles: "sync" effect's implementation returned a promise, and the yield threw SyncEffectPromiseError. Once per effect type, whether or not the action caught the error. Data: { effectType }. Usually an async implementation, a test stub or a lazy loader. Do: return the value directly, or drop settles: "sync" (effects.md).
effect/sync-promise-rejected
The promise behind effect/sync-returned-promise later rejected. Every rejection. Data: { effectType, cause }, cause being the implementation's real failure; a redacted type has no cause.
State
state/outside-action-write
A write reached the state tree outside a step of the action that owns it, from a timer, a promise callback or another action's body, and threw a TreflexRefusal. Every time. Data: { path }. Do: dispatch an action and write through its draft in its own steps; an external system pushing state in is a resource.
state/view-write
A write went through a read-only state view, runtime.state, a view's state, or a selector's argument, and threw a TreflexRefusal. Every time. Data: { key, verb }. Do: dispatch an action.
entity/replaced-by-plain-data
A write replaced entities with plain data carrying no $Id, and something was attached to them, which has ended: a binding, timers, resources, running actions. A replaced entity with nothing attached reports nothing. It refuses nothing. Once per container per write. Data: { at, entities }, up to ten entities, each with its id and attachments. Do: for a refresh, use reconcileRows, which keeps the rows that match and what is attached to them; to load one entity, write its fields; to make a new one, use entity() (write-path.md).
selector/many-tracked-reads
One run of a selector tracked more than 50,000 reads, so a change to any of them re-runs all of it. Once per selector function. Data: { selector, trackedReads }, selector being the function's name. Do: read less per run, or derive per row with a selector on each row, memoized per entity (derived-reads.md).
Outside values
external/unprovided
A selector or an action read external(key) and nothing provides the key on this runtime, so it read undefined. Once per key. Data: { key }. Do: provide the key in setup, the function a fresh boot and a restore both call (providing a value).
external/replaced
provideExternal was called for a key already provided. The first provider's subscription is stopped and its handle does nothing, and the key's readers re-run on the new provider's value. Every replacement. Data: { key }. Do: provide each key once, in setup.
Receivers
receiver/unresolved
Something names a receiver that isn't registered, so nothing ran for it. Nothing is removed, and registering the receiver heals it. data.kind tells the producers apart:
kind | When | Once per | Data |
|---|---|---|---|
"binding" | Entities are bound to an unregistered receiver; a microtask after the binding lands | Receiver id | { receiverId, ownerIds, count }, up to ten owners |
"publish" | A publishToNearest walk stopped at an ancestor bound to an unregistered receiver | Topic, stopping entity and receiver | { topic, ownerId, receiverId, shadowedId }, shadowedId the nearest handler above it, or null |
"timer" | A tick found its receiver unregistered, skipped, and re-armed | Key, owner and receiver, cleared by a tick that reaches it | { key, ownerId, receiverId } |
"resource" | A resource row's receiver is unregistered; the resource waits unconnected | Key, owner and receiver | { key, ownerId, receiverId } |
Do: register the receiver at startup with runtime.registerReceiver(Receiver).
For a receiver that doesn't fire, see messaging.md.
receiver/id-collision
A receiver id was registered again with a different handle, in a production build, where it means two modules claim one id; a development build stays silent, since there it is a hot reload. The later registration wins, and every entity bound to the id and every timer row naming it dispatch into it from then on. Every such registration. Data: { id }. Do: check the receiver exports and the glob that registers them.
Resources
Each names the key and the owner.
resource/unregistered-type
A row names a type no registerResourceType has registered. The row is recorded and waits, pending on "type", until the type registers. Once per type, key and owner. Data: { type, key, ownerId }.
resource/ended
An instance ended by itself because its setup threw, its implementation rejected, or an onIdle callback threw. The receiver gets $Ended with Reason: "failed" and the error. Every time. Data: { key, ownerId, error }, error the serialized throw, as $Ended carries it.
resource/invalid-message
r.emit was given a message that isn't plain data, is an array, or carries Type or a top-level $-prefixed field. It wasn't delivered. Every time. Data: { key, ownerId }. Do: wrap it, { Event: wire }, or encode it.
resource/queue-depth
More than 100 emits are queued behind the receiver. Once per instance. Data: { key, ownerId, depth }. Do: batch what arrives and emit it from r.onIdle, or make the receiver quicker.
resource/receiver-waiting
A receiver a resource delivered to waited on a resource method or an ask, so every later delivery to the cell waits behind it. Once per key, owner and effect type. Data: { key, ownerId, effectType }. Do: run that work in an action the receiver starts, yield* start(...).
resource/not-open
A method found no row for its key and owner, and resolved undefined. Once per key and owner. Data: { key, ownerId }. Do: check that openResource ran, and the key and owner.
resource/used-after-end
A method found the resource ended, and resolved undefined. Once per key and owner. Data: { key, ownerId }. Do: reopen it to use it again.
resource/unknown-method
A method the type didn't register was called, and resolved undefined. Once per key and method. Data: { key, method, type }.
resource/supply-dropped
A supplied value had no taker and was dropped; the supply resolved undefined, and the view still holds the value. Every time. Data: { key, ownerId, reason }, reason one of "no owner" (a useResource owner accessor answered undefined), "no open resource", "paused", "no live instance", "retired before setup" or "no onSupply registered".
resource/still-paused
A restore's repair hasn't settled 3 seconds after the load, and every resource stays paused until it does. Never under a permanent pause. Once per restore. Data: { repair }, the repair function's name or null.
Restore
restore/malformed-rows
The restore dropped malformed rows from the envelope's tables or in-flight list, and loaded the rest. Once per restore. Data: { droppedRows }.
restore/orphaned-rows
The restore left out table rows whose owners aren't in the restored tree, counted in the result's sweptOrphanedRows. Once per restore. Data: { count }.
restore/unresolved-receiver
Restored bindings, timer rows or resource rows name receivers this build hasn't registered, typically one renamed between deploys. They stay, and deliver nothing until registered; the result's unresolved lists them. Once per restore. Data: { count, receiverIds, sample }, up to ten of each. Do: register the receivers in setup, or unbind the entities and retract the rows.
The runtime
runtime/callback-threw
Code the runtime calls outside any action threw. Only that call is lost: a tap or subscriber stays attached, and the runtime goes on. The code: a record tap, a runtime.on subscriber, a cached read's dispose, a resource's release of an exposed value, a resource manager task, a dispose callback, an onDrained listener, a React view's store listener, a view reading inFlight or pendingAsks, or the function an outside value's subscribe returned. Every throw. Data: { source, error }, the live error, with kind, entityId, ownerId or key where there is one.
Console warnings
These go to the console only, with no code and no diag event:
| Warning | When |
|---|---|
registerDataSource(...) owner not in the state tree | The owner's $Id isn't in the tree, so nothing will remove the registration |
registerDataSource(...) owner already owns the key | A second registration of a key on one owner, which replaces the data |
getData(...) or getDataPath(...) called from an entity not in the state tree | from's $Id isn't in the tree; the read answers undefined |
startTimer called from an entity not in the state tree | The row is written, and its first tick removes it |
publishToNearest called from an entity not in the state tree | Nothing is delivered, and no record lands |
| Implementation for an effect being overwritten | registerImplementation for a type that has one |
| Effect declared again with different options | defineEffect for a type declared with other options, which replaces them |
draft/stale-path-write, draft/stale-path-delete | With a record tap attached: a write through a held reference to a node that has since moved, so its record names a path another node holds. Once per node |
draft/orphaned-write, draft/orphaned-delete | With a record tap attached: a write through a held reference to a node that left the tree in this step, which lands on the detached node unseen. Once per node |
A non-Error throw doesn't survive JSON serialization | A thrown value with no faithful JSON form; its records and Action/Error payload carry a different value |
For a registration warning, register from the draft the action was given or an entity under it. For a draft warning, write through a reference found again from the draft after whatever moved or replaced the node (actions.md).