Troubleshooting
Find what you see, then why it happens and what to do. Errors carry a stable code: branch on it, never on the message.
Unexpected answers
holds answers false, but canon says it happened
holds: falseWhy
A Fact is canon, not anyone’s knowledge. Nobody holds a claim without a Holding of their own.
Fix
Write a Holding for each character who knows it: in the same commit, or with witness for everyone at the scene.
Someone at the scene knows nothing about it
holds: falseWhy
Participants of an event hold nothing because they were there.
Fix
Give them Holdings acquired witnessed at the event. witness does it for every witness and claim in one call.
await client.witness({
projectId, attemptId: 'scene-4', event,
claims: [{ claim: theft }],
witnesses: [{ holder: 'ana' }, { holder: 'bob' }],
});A belief is there in one read and missing in another
holds: falseWhy
Reads stand at at: an earlier tick or version does not see it yet, a read on another axis sees only events placed on it, and a read of main does not see what was written to a draft.
Fix
Check at.tick, at.asOfVersion, at.axis and timelineId. Without them a read is at the latest position of main, on the main axis.
Two different values, and contradictions reports nothing
cardinalityWhy
Only a predicate of cardinality one has a single value per subject. Two values of a many predicate can both be true.
Fix
Declare the predicate with cardinality: "one" when a subject can have only one value at a time, such as where someone is.
Refused writes
A field is refused although it looks right
VALIDATION_FAILEDWhy
Payloads are strict: an unknown key is refused, and details.unknownField names it. att is not at.
Fix
Fix the name. Every operation’s page lists its fields.
{
"code": "VALIDATION_FAILED",
"details": { "unknownField": "att" }
}“Predicate does not exist”
VALIDATION_FAILEDWhy
Projects are strict by default: a claim needs its predicate declared first.
Fix
Call predicate.define, or create the project with vocabularyMode: "open" to accept new predicates with an UNKNOWN_PREDICATE warning.
“Entity cannot be a holder”
VALIDATION_FAILEDWhy
Only entities of an agent or group type hold knowledge. Places and objects are other.
Fix
Use an entity type of kind agent or group for anyone who knows things.
“A commit must carry at least one record or transition”
VALIDATION_FAILEDWhy
An event alone records nothing anyone could know or change. Batch operations likewise refuse an empty list.
Fix
Add the records the event writes, or skip the call when there is nothing to write.
Creating something fails with “already exists”
CONFLICTWhy
Projects, entity types, entities and evidence sources keep their id: creating one with an id that is taken is refused, and the stored one is left as it was. Defining a predicate again with a different definition is refused too, with the stored one in details.predicate.
Fix
Use another id, or read the one that exists. To register entities from your own system without caring whether they exist yet, use entity.ensureBatch.
A retried write is refused
CONFLICTWhy
The same attemptId was used for a different request. A real retry sends the identical request and gets the stored outcome.
Fix
Give each new write its own attempt id; reuse it only to retry that exact write.
A write fails with a version conflict
VERSION_CONFLICTWhy
It carried an expectedVersion, and the timeline moved since you read it.
Fix
Read again, decide whether the write still makes sense, and send it with the new version.
Drafts
Promote fails after the parent moved
VERSION_CONFLICTWhy
A draft can only be promoted into its parent as the draft saw it. details has the draft’s base and the parent’s head.
Fix
Call timeline.rebase to replay the draft on the new head, then promote. See Save and load the day.
An id is taken after the draft was thrown away
CONFLICTWhy
A discarded draft keeps its ids reserved until it is purged.
Fix
Discard with purge: true when you will replay the same work with the same ids.
Reading a draft fails after promoting it
INVALID_STATEWhy
A promoted draft is part of its parent now.
Fix
Read the timeline named in details.promotedInto.
A draft cannot be discarded, purged or rebased
INVALID_STATEWhy
Other drafts were opened from it and still depend on it; details.descendants lists them.
Fix
Promote, discard or purge those drafts first.
Files and processes
The file is already open
FILE_LOCKEDWhy
One process owns a .umw file at a time.
Fix
Keep one umwelt serve or one engine per file, and send every request through it.
Every request answers HANDSHAKE_REQUIRED
HANDSHAKE_REQUIREDWhy
Over the protocol, the first request must be hello.
Fix
Send hello first. The client libraries and umwelt call do it for you.
{"v":1,"id":"1","op":"hello","payload":{"protocol":{"min":1,"max":1},"client":"my-game/1.0"}}The file is from a newer engine
UNSUPPORTED_FILE_VERSIONWhy
The file was written with a newer storage version than this engine reads.
Fix
Update the engine. Files of earlier storage versions are migrated forward automatically when they are opened.
The file is not an Umwelt file
NOT_UMWELT_FILEWhy
The SQLite file does not carry Umwelt’s application id: it was made by something else.
Fix
Create the file with umwelt create, create: true in TypeScript or UmweltEngine.Create in .NET.
Search
A search finds nothing
items: []Why
Without a holder, search sees Facts and events; with one, only that holder’s active, available Holdings that have text. Engine events such as umwelt:transmit are not searchable.
Fix
Give Holdings a text to find them by words, and check the holder, the position and the timeline.
Semantic search misses new documents
embedding.pendingWhy
Vectors come from your model. New documents, and documents whose text changed, have none until you store one.
Fix
List them with embedding.pending and store vectors with embedding.put, or let the TypeScript client do it with autoEmbed.
Every error code is listed in Errors. Still stuck? The FAQ may have it.