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 | string | None | — |
message | string | None | — |
path | Maybe(string) | None | nil |
field | Maybe(string) | None | nil |
entity | Maybe(builtin.i64) | None | nil |
offset | Maybe(builtin.i64) | Bytes | nil |
status | 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 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, child_iterator |
| start is past the last node or capacity is negative | read_many |
| id is not an object node of the document | member |
| 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 | page_iterator, 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, builder, add, add_many, seal, build, build_macro, expand_macro, evaluate, open, query, mutation, expression, run, next, page_iterator, 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, root, count, read, read_many, member, child_iterator, 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, page_iterator, 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
failed, result := stardust.backups_status(db)
defer stardust.close(&failed)
defer stardust.close(&result){
"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
sync_options := stardust.parse(`{maxWait {#dur PT5S}}`, .DUST) or_return
defer stardust.close(&sync_options)
result := stardust.backups_sync(db, sync_options)
defer stardust.close(&result){
"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}"
source := stardust.parse(duplicate_text, .JSON) or_return
defer stardust.close(&source)
view := stardust.read(source, stardust.root(source) or_return) or_return
failed, result := stardust.parse(view.text, .EDN)
defer stardust.close(&failed)
defer stardust.close(&result){
"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"
}
}
patch := stardust.parse(patch_text, .JSON) or_return
defer stardust.close(&patch)
commit, result := stardust.merge_patch(db, patch)
defer stardust.close(&commit)
defer stardust.close(&result){
"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"
}
}
}
future := stardust.parse(future_text, .JSON) or_return
defer stardust.close(&future)
committed := stardust.merge_patch(db, future) or_return
defer stardust.close(&committed)
patch := stardust.parse(older_text, .JSON) or_return
defer stardust.close(&patch)
commit, result := stardust.merge_patch(db, patch)
defer stardust.close(&commit)
defer stardust.close(&result){
"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
query_text holds this document:
{
"find": [
"?x"
]
}
definition := stardust.parse(query_text, .JSON) or_return
defer stardust.close(&definition)
query, result := stardust.query(db, definition)
defer stardust.close(&query)
defer stardust.close(&result){
"code": "unbound_variable",
"message": "Unbound_Variable",
"path": null,
"field": null,
"entity": null,
"offset": null,
"status": "invalid_definition"
}Report a missing stored query
query, result := stardust.query(db, "people/missing")
defer stardust.close(&query)
defer stardust.close(&result){
"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 holds these bytes:
]
failed, result := stardust.parse(malformed, .DUST)
defer stardust.close(&failed)
defer stardust.close(&result){
"code": "invalid_dust",
"message": "Invalid_Syntax at offset 0",
"path": null,
"field": null,
"entity": null,
"offset": 0,
"status": "invalid_argument"
}Report malformed DUST
malformed holds these bytes:
[
failed, result := stardust.parse(malformed, .DUST)
defer stardust.close(&failed)
defer stardust.close(&result){
"code": "invalid_dust",
"message": "Unexpected_End at offset 2",
"path": null,
"field": null,
"entity": null,
"offset": 2,
"status": "invalid_argument"
}