Errors
A call can fail because a definition is missing, a document is invalid, or the database refuses a change. The examples use the people data to show these results. Use the status and diagnostic fields to identify the failure.
Binding errors
| Language | Failure |
|---|---|
| C | Returns a status. The owner that its operation names holds the diagnostic. |
| Go | Returns *Error. |
| Rust | Returns Result<_, Error>. |
| Clojure | Throws clojure.lang.ExceptionInfo with diagnostic data. |
| Python | Raises StardustError. |
| Odin | Returns an Error beside its result. |
The error record gives the fields in your language. Statuses gives the failure conditions of each operation.
error
This record describes a failure with its status and diagnostic. The binding copies the diagnostic before it releases the native owner.
| Field | Type | Unit | Absent |
|---|---|---|---|
code | Copied-Text | None | — |
message | Copied-Text | None | — |
path | Reported-Text | None | An absent key |
field | Reported-Text | None | An absent key |
entity | Reported-Integer | None | An absent key |
offset | Reported-Integer | Bytes | An absent key |
status | Error-Status | None | — |
Statuses
Each status names a class of failure. The table lists codes from the binding. Native diagnostic codes can differ.
:invalid-argument
Codes: time_out_of_range, invalid_argument, out_of_range, non_finite_number, cycle, unsupported_type, too_large, native_failure, live_children, wrong_kind, not_integral, inexact_number, missing_field, unknown_field, duplicate_field, too_deep, length_mismatch, malformed_tag, ambiguous_field, ambiguous_variant, invalid_value, hook_failed.
| When | Operations |
|---|---|
the entity ID is outside the user entity range, max_depth is negative or above 32, or max_entities is negative | read-entity |
the text is malformed, the format is unknown or a number is outside i64 or finite f64 | parse |
| the format is unknown or the width is negative | serialize |
| the text is malformed, a format is unknown or the width is negative | convert |
the value has a host type with no document form (one the language's standard JSON encoder also refuses), a number outside i64 or finite f64, a decimal or time with no exact native form, a failing conversion method, or a cycle | from-value |
| the node breaks the preorder rules or has an invalid kind or number | add |
| a node breaks the preorder rules or has an invalid kind or number | add-many |
| the builder has no root or a container is still open | seal |
| id is not a node of the document | read, children |
| start is past the last node or capacity is negative | read-many |
| id is not an object node of the document | member, members |
| the node is not an integer number | i64 |
the node is not a number or its value overflows f64 | f64 |
| the arguments include an undeclared macro parameter | build-macro, expand-macro |
| the file is not a database, an option is invalid or selected plugins are incompatible | open |
| the parameters or run options are invalid | run, run |
| the parameters or subscription options are invalid | subscribe |
max_wait is negative | next, indexes-sync |
| the patch is not an entity-keyed object, or a link names an ID outside the user entity range | merge-patch |
| the kind, action, revision or page limits are invalid, or the selected plan cannot run the current authored definition | plan |
| the kind or the pattern is invalid | definitions |
| a bulk build is already in progress on the database | bulk-begin |
| no bulk build is in progress | bulk-add, bulk-finish |
| a name is empty, the plugin has no call operation with the name, or the plugin refuses the request | plugin-call |
| a name is empty, the plugin has no stream operation with the name, or the plugin refuses the request | plugin-stream |
| the stream has finished or does not accept writes | write |
| the stream does not support reads, or length is negative | read |
the stream does not support seeks, whence is unknown, or the position is negative or past the i64 range | seek |
| the stream has finished or has no finish step | finish |
| the token is empty or longer than 4096 bytes | activate |
| entity is not a user entity | objects-get, objects-path |
| the parent or the name is invalid, or the parent is a file | objects-lookup |
| the parent is invalid or is a file | objects-children |
| the digest is not 64 hexadecimal digits | objects-files, objects-manifest, objects-open |
| the array is empty or malformed, a name is invalid, or a parent is a file | objects-create |
the entity is a directory or invalid, the digest is malformed, or expected_revision is negative | objects-update |
| the request is malformed, the destination is a file or inside the node, the kinds differ, or a replaced directory is not empty | objects-move |
the entity is invalid, the directory is not empty, or expected_revision is negative | objects-remove |
| options is not an object, or an option is invalid, duplicated or unsupported | reactors-sync, backups-sync, sdk-sync |
:invalid-json
:compile-failed
| When | Operations |
|---|---|
| the expression does not compile | build |
| the expansion does not compile | build-macro |
| the expanded expression does not compile | expression |
:evaluation-failed
| When | Operations |
|---|---|
| the expression fails on the input | evaluate |
the query fails or exceeds max_cost | run |
| the page does not render | next |
| a page does not render | pages, all-pages |
| a rerun of the query failed. Every later call reports this failure | next |
| the mutation fails | run |
| the plugin cannot read its stored state | plugin-call, plugin-stream |
| stored bytes do not match their digest | read |
| stored tree metadata or the manifest of a named payload is corrupted | objects-get, objects-lookup, objects-children, objects-path |
| the stored manifest is corrupted | objects-manifest, objects-open |
:out-of-memory
Codes: out_of_memory.
| When | Operations |
|---|---|
| native memory is exhausted | read-entity, parse, serialize, convert, from-value, builder, add, add-many, seal, build, build-macro, expand-macro, evaluate, open, query, mutation, expression, run, next, pages, all-pages, subscribe, next, run, merge-patch, definition, plan, definitions, patch-definition, bulk-begin, bulk-add, bulk-finish, plugin-call, plugin-stream, finish, plugins, objects-get, objects-lookup, objects-children, objects-path, objects-files, objects-manifest, objects-create, objects-update, objects-move, objects-remove, objects-upload, objects-open, reactors-status, backups-status, sdk-status |
:not-found
Codes: not_found.
| When | Operations |
|---|---|
| the object has no member with the key | member |
| the macro refers to an unknown macro | build-macro, expand-macro |
| the parent directory is missing, or the file is missing and create is false | open |
| no definition is stored at the path | query, mutation, definition |
| no expression is stored at the path | expression |
| the stored query definition was deleted | run |
| the definition or exact historical plan revision does not exist | plan |
| the plugin reports that the request names nothing it holds | plugin-call, plugin-stream |
| no object node has the entity | objects-get |
| the parent has no child with the name, or the parent does not exist | objects-lookup |
| the parent does not exist | objects-children |
| the node or one of its ancestors does not exist | objects-path |
| no payload with the digest is published | objects-manifest, objects-open |
| a parent does not exist or a digest is not published | objects-create |
| the file does not exist or the digest is not published | objects-update |
| the node or the destination does not exist | objects-move |
| the node does not exist | objects-remove |
:locked
| When | Operations |
|---|---|
another process holds the lock after lock_timeout | open |
:conflict
| When | Operations |
|---|---|
an enabled plugin finds the database inconsistent with its copies: backups refuse diverging copies with code backup_history_divergent, naming them | open |
| concurrent writes prevent the commit | run |
| an entity revision check fails or a concurrent writer prevents the commit; a revision mismatch reports the entity and expected and actual revisions | merge-patch |
| the authored definition or accepted plan changed before the explicit control committed | plan |
| another write committed to the database during the build | bulk-finish |
| the plugin's write lost to a concurrent change, or the database holds writes | plugin-call |
| the database holds writes | plugin-stream, finish, objects-upload |
| the database holds writes while the plugin stores the bytes | write |
| a name is already taken in its parent or appears twice, or the database holds writes | objects-create |
expected_revision is stale, or the database holds writes | objects-update, objects-remove |
the name is occupied without replace, expected_revision is stale, or the database holds writes | objects-move |
:invalid-definition
| When | Operations |
|---|---|
| the macro is invalid or expands recursively | build-macro, expand-macro |
| the definition is invalid | query, mutation |
| a macro it calls is invalid or expands recursively | expression |
| the loaded query definition is invalid | run |
| the query or its callable definitions are invalid | subscribe |
| the mutation selection or definition is invalid | run |
| the patched definition is invalid | patch-definition |
:schema-violation
| When | Operations |
|---|---|
| the write breaks a schema | run |
:invalid-commit-time
| When | Operations |
|---|---|
the #_tx commit time is not later than the last commit | merge-patch |
:closed
Codes: closed.
| When | Operations |
|---|---|
| the database is closed | read-entity, query, mutation, expression, merge-patch, definition, plan, definitions, patch-definition, indexes-sync, bulk-begin, bulk-add, bulk-finish, plugin-call, plugin-stream, objects-get, objects-lookup, objects-children, objects-path, objects-files, objects-manifest, objects-create, objects-update, objects-move, objects-remove, objects-upload, objects-open, reactors-status, reactors-sync, backups-status, backups-sync, sdk-status, sdk-sync |
| the document is closed | serialize, to-value, root, count, read, read-many, member, children, members, i64, f64 |
| the builder is closed | add, add-many, seal |
| the program is closed | evaluate |
| the query is closed | run, subscribe |
| the rows is closed | next, pages, all-pages |
| the subscription is closed | next |
| the mutation is closed | run |
the plugin_stream is closed | write, read, seek, finish |
:rejected
| When | Operations |
|---|---|
| a mutation target or write guard refuses the write | run |
| the database refuses the patch; the code and diagnostic path name the reason and key | merge-patch |
| the database refuses the patch; the build has failed and later adds report the same status | bulk-add |
| the database refuses a patch; an initial build publishes nothing and fallback keeps earlier commits | bulk-finish |
:unsupported
Codes: abi_version, core_digest.
| When | Operations |
|---|---|
| found differs from the ABI version of the binding | check-version |
:cancelled
Codes: cancelled.
| When | Operations |
|---|---|
| the subscription is cancelled or closed | next |
:timeout
| When | Operations |
|---|---|
max_wait passed first | indexes-sync |
| the plugin's wait passed its limit | plugin-call |
| maxWait passed before the work finished | reactors-sync, sdk-sync |
| maxWait passed before every target confirmed | backups-sync |
:unavailable
| When | Operations |
|---|---|
an enabled plugin cannot reach what the open needs: backups refuse with backup_targets_unreachable, backup_target_unreadable or backup_objects_required | open |
| the patch sets stardust/history and no enabled plugin purges history | run, merge-patch |
| the plugin is unknown or the database does not enable it | plugin-call, plugin-stream |
| the database does not enable the objects plugin | objects-get, objects-lookup, objects-children, objects-path, objects-files, objects-manifest, objects-create, objects-update, objects-move, objects-remove, objects-upload, objects-open |
| the database does not enable the reactors plugin | reactors-status, reactors-sync |
| the database does not enable the backups plugin | backups-status, backups-sync |
| the database does not enable the sdk plugin | sdk-status, sdk-sync |
:failed
| When | Operations |
|---|---|
| the plugin's work failed | plugin-call |
| the plugin's work failed; status describes the failure | reactors-sync, backups-sync, sdk-sync |
:unlicensed
Codes: unlicensed.
| When | Operations |
|---|---|
| the token is refused; the error names the reason | activate |
Refusal examples
The generator captured each result from the native library.
Describe the backup runtime
(sd/backups-status db){
"code": "unavailable",
"message": "the plugin is not enabled",
"path": null,
"field": null,
"entity": null,
"offset": null,
"status": "unavailable"
}Wait until every target stored the history
(with-open [sync-options (sd/parse "{maxWait {#dur PT5S}}" :dust)]
(sd/backups-sync db sync-options)){
"code": "unavailable",
"message": "the plugin is not enabled",
"path": null,
"field": null,
"entity": null,
"offset": null,
"status": "unavailable"
}convert
duplicate-text holds this document:
"{:a 1 :a 2}"
(with-open [source (sd/parse duplicate-text :json)]
(sd/parse (:text (sd/read source (sd/root source))) :edn)){
"code": "invalid_edn",
"message": "invalid EDN (Duplicate_Key) at offset 6",
"path": null,
"field": null,
"entity": null,
"offset": 6,
"status": "invalid_argument"
}Refuse a metadata-only transaction
patch-text holds this document:
{
"#_tx": {
"author": "x"
}
}
(with-open [patch (sd/parse patch-text :json)]
(sd/merge-patch db patch)){
"code": "transaction_only",
"message": "a patch of only #_tx is refused: #_tx annotates a write",
"path": "#_tx",
"field": null,
"entity": null,
"offset": null,
"status": "rejected"
}Refuse a repeated commit time
future-text holds this document:
{
"#_d": {
"x": 1
},
"#_tx": {
"stardust/committedAt": {
"#utc": "2200-01-01T00:00:00Z"
}
}
}
older-text holds this document:
{
"#_e": {
"x": 2
},
"#_tx": {
"stardust/committedAt": {
"#utc": "2200-01-01T00:00:00Z"
}
}
}
(with-open [future (sd/parse future-text :json)
older (sd/parse older-text :json)]
(sd/merge-patch db future)
(sd/merge-patch db older)){
"code": "invalid_commit_time",
"message": "stardust/committedAt must be strictly newer than the latest commit time",
"path": null,
"field": null,
"entity": null,
"offset": null,
"status": "invalid_commit_time"
}Refuse an invalid query definition
definition-text holds this document:
{
"find": [
"?x"
]
}
(with-open [definition (sd/parse definition-text :json)]
(sd/query db definition)){
"code": "unbound_variable",
"message": "Unbound_Variable",
"path": null,
"field": null,
"entity": null,
"offset": null,
"status": "invalid_definition"
}Report a missing stored query
(sd/query db "people/missing"){
"code": "not_found",
"message": "no definition at this path",
"path": "people/missing",
"field": null,
"entity": null,
"offset": null,
"status": "not_found"
}Report a malformed byte at offset zero
malformed-text holds these bytes:
]
(sd/parse malformed-text :dust){
"code": "invalid_dust",
"message": "Invalid_Syntax at offset 0",
"path": null,
"field": null,
"entity": null,
"offset": 0,
"status": "invalid_argument"
}Report malformed DUST
malformed-text holds these bytes:
[
(sd/parse malformed-text :dust){
"code": "invalid_dust",
"message": "Unexpected_End at offset 2",
"path": null,
"field": null,
"entity": null,
"offset": 2,
"status": "invalid_argument"
}