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.
stardust_diagnostic_view
This record describes a failure with its status and diagnostic. The binding copies the diagnostic before it releases the native owner.
| Field | C type | Unit | Range | Default | Absent | Meaning |
|---|---|---|---|---|---|---|
code | stardust_bytes | None | C type range | The call sets it | Always present | — |
message | stardust_bytes | None | C type range | The call sets it | Always present | — |
path | stardust_bytes | None | C type range | The call sets it | present & STARDUST_DIAGNOSTIC_PATH is zero | Read this field only when present & STARDUST_DIAGNOSTIC_PATH is not zero. The call can report an empty string or zero. |
field | stardust_bytes | None | C type range | The call sets it | present & STARDUST_DIAGNOSTIC_FIELD is zero | Read this field only when present & STARDUST_DIAGNOSTIC_FIELD is not zero. The call can report an empty string or zero. |
entity | int64_t | None | Signed i64 | The call sets it | present & STARDUST_DIAGNOSTIC_ENTITY is zero | Read this field only when present & STARDUST_DIAGNOSTIC_ENTITY is not zero. The call can report an empty string or zero. |
offset | int64_t | Bytes | Signed i64 | The call sets it | present & STARDUST_DIAGNOSTIC_OFFSET is zero | Read this field only when present & STARDUST_DIAGNOSTIC_OFFSET is not zero. The call can report an empty string or zero. |
present | uint32_t | None | Unsigned u32 | The call sets it | Always present | Presence-bit mask: test each STARDUST_DIAGNOSTIC_* bit before you read its optional field. |
reserved | uint32_t | None | Unsigned u32 | 0 | Always present | Must be zero. |
Statuses
A C call returns its status. Examine a returned error owner when the operation provides one. Status-only calls have no new diagnostic.
STARDUST_INVALID_ARGUMENT
| When | Operations |
|---|---|
the entity ID is outside the user entity range, max_depth is negative or above 32, or max_entities is negative | stardust_db_read_entity |
| a required input or output pointer is NULL, or an input owner is not ready | stardust_abi_version, stardust_document_builder_create, stardust_document_root, stardust_document_count, stardust_expr_build, stardust_expr_evaluate, stardust_db_query_open, stardust_db_mutation_open, stardust_db_expression_build, stardust_db_rows_next, stardust_db_definition_get, stardust_db_definition_patch, stardust_plugins, stardust_license |
the text is malformed, the format is unknown or a number is outside i64 or finite f64 | stardust_parse |
| the format is unknown or the width is negative | stardust_serialize |
| a node breaks the preorder rules or has an invalid kind or number | stardust_document_builder_add_many |
| the builder has no root or a container is still open | stardust_document_builder_seal |
| start is past the last node or capacity is negative | stardust_document_read_many |
| id is not an object node of the document | stardust_document_member |
| the node is not an integer number | stardust_document_i64 |
the node is not a number or its value overflows f64 | stardust_document_f64 |
| the arguments include an undeclared macro parameter | stardust_macro_build, stardust_macro_expand |
| the file is not a database, an option is invalid or selected plugins are incompatible | stardust_db_open |
| the parameters or run options are invalid | stardust_db_query_run, stardust_db_mutation_run |
| the parameters or subscription options are invalid | stardust_db_query_subscribe |
max_wait is negative | stardust_db_subscription_next, stardust_db_indexes_sync |
| the patch is not an entity-keyed object, or a link names an ID outside the user entity range | stardust_db_merge_patch |
| the kind, action, revision or page limits are invalid, or the selected plan cannot run the current authored definition | stardust_db_plan |
| the kind or the pattern is invalid | stardust_db_definition_list |
| a bulk build is already in progress on the database | stardust_db_bulk_begin |
| no bulk build is in progress | stardust_db_bulk_add, stardust_db_bulk_finish |
| a name is empty, the plugin has no call operation with the name, or the plugin refuses the request | stardust_db_plugin_call |
| a name is empty, the plugin has no stream operation with the name, or the plugin refuses the request | stardust_db_plugin_stream_open |
| the stream has finished or does not accept writes | stardust_db_plugin_stream_write |
| the stream does not support reads, or length is negative | stardust_db_plugin_stream_read |
the stream does not support seeks, whence is unknown, or the position is negative or past the i64 range | stardust_db_plugin_stream_seek |
| the stream has finished or has no finish step | stardust_db_plugin_stream_finish |
| the token is empty or longer than 4096 bytes | stardust_activate |
STARDUST_INVALID_JSON
| When | Operations |
|---|---|
| JSON text is malformed | stardust_parse |
STARDUST_COMPILE_FAILED
| When | Operations |
|---|---|
| the expression does not compile | stardust_expr_build |
| the expansion does not compile | stardust_macro_build |
| the expanded expression does not compile | stardust_db_expression_build |
STARDUST_EVALUATION_FAILED
| When | Operations |
|---|---|
| the expression fails on the input | stardust_expr_evaluate |
the query fails or exceeds max_cost | stardust_db_query_run |
| the page does not render | stardust_db_rows_next |
| a rerun of the query failed. Every later call reports this failure | stardust_db_subscription_next |
| the mutation fails | stardust_db_mutation_run |
| the plugin cannot read its stored state | stardust_db_plugin_call, stardust_db_plugin_stream_open |
| stored bytes do not match their digest | stardust_db_plugin_stream_read |
STARDUST_OUT_OF_MEMORY
STARDUST_NOT_FOUND
| When | Operations |
|---|---|
| the object has no member with the key | stardust_document_member |
| the macro refers to an unknown macro | stardust_macro_build, stardust_macro_expand |
| the parent directory is missing, or the file is missing and create is false | stardust_db_open |
| no definition is stored at the path | stardust_db_query_open, stardust_db_mutation_open, stardust_db_definition_get |
| no expression is stored at the path | stardust_db_expression_build |
| the stored query definition was deleted | stardust_db_query_run |
| the definition or exact historical plan revision does not exist | stardust_db_plan |
| the plugin reports that the request names nothing it holds | stardust_db_plugin_call, stardust_db_plugin_stream_open |
STARDUST_LOCKED
| When | Operations |
|---|---|
another process holds the lock after lock_timeout | stardust_db_open |
STARDUST_CONFLICT
| When | Operations |
|---|---|
an enabled plugin finds the database inconsistent with its copies: backups refuse diverging copies with code backup_history_divergent, naming them | stardust_db_open |
| concurrent writes prevent the commit | stardust_db_mutation_run |
| an entity revision check fails or a concurrent writer prevents the commit; a revision mismatch reports the entity and expected and actual revisions | stardust_db_merge_patch |
| the authored definition or accepted plan changed before the explicit control committed | stardust_db_plan |
| another write committed to the database during the build | stardust_db_bulk_finish |
| the plugin's write lost to a concurrent change, or the database holds writes | stardust_db_plugin_call |
| the database holds writes | stardust_db_plugin_stream_open, stardust_db_plugin_stream_finish |
| the database holds writes while the plugin stores the bytes | stardust_db_plugin_stream_write |
STARDUST_INVALID_DEFINITION
| When | Operations |
|---|---|
| the macro is invalid or expands recursively | stardust_macro_build, stardust_macro_expand |
| the definition is invalid | stardust_db_query_open, stardust_db_mutation_open |
| a macro it calls is invalid or expands recursively | stardust_db_expression_build |
| the loaded query definition is invalid | stardust_db_query_run |
| the query or its callable definitions are invalid | stardust_db_query_subscribe |
| the mutation selection or definition is invalid | stardust_db_mutation_run |
| the patched definition is invalid | stardust_db_definition_patch |
STARDUST_SCHEMA_VIOLATION
| When | Operations |
|---|---|
| the write breaks a schema | stardust_db_mutation_run |
STARDUST_INVALID_COMMIT_TIME
| When | Operations |
|---|---|
the #_tx commit time is not later than the last commit | stardust_db_merge_patch |
STARDUST_CLOSED
STARDUST_REJECTED
| When | Operations |
|---|---|
| a mutation target or write guard refuses the write | stardust_db_mutation_run |
| the database refuses the patch; the code and diagnostic path name the reason and key | stardust_db_merge_patch |
| the database refuses the patch; the build has failed and later adds report the same status | stardust_db_bulk_add |
| the database refuses a patch; an initial build publishes nothing and fallback keeps earlier commits | stardust_db_bulk_finish |
STARDUST_UNSUPPORTED
No core operation reports this status.
STARDUST_CANCELLED
| When | Operations |
|---|---|
| the subscription is cancelled or closed | stardust_db_subscription_next |
STARDUST_TIMEOUT
| When | Operations |
|---|---|
max_wait passed first | stardust_db_indexes_sync |
| the plugin's wait passed its limit | stardust_db_plugin_call |
STARDUST_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 | stardust_db_open |
| the patch sets stardust/history and no enabled plugin purges history | stardust_db_mutation_run, stardust_db_merge_patch |
| the plugin is unknown or the database does not enable it | stardust_db_plugin_call, stardust_db_plugin_stream_open |
STARDUST_FAILED
| When | Operations |
|---|---|
| the plugin's work failed | stardust_db_plugin_call |
STARDUST_UNLICENSED
| When | Operations |
|---|---|
| the token is refused; the error names the reason | stardust_activate |
Refusal examples
The generator captured each result from the native library.
convert
duplicate_text holds this document:
"{:a 1 :a 2}"stardust_document *source = NULL;
uint32_t root = 0;
stardust_node_view view = {0};
int64_t written = 0;
uint32_t status = stardust_parse(duplicate_text, STARDUST_EDN, &source);
if (status == STARDUST_OK) status = stardust_document_root(source, &root);
if (status == STARDUST_OK) status = stardust_document_read_many(source, root, 1, &view, &written);
if (status != STARDUST_OK) {stardust_document_release(source); return status;}
stardust_document *failed = NULL;
status = stardust_parse(view.text, STARDUST_EDN, &failed);
stardust_document_release(source);
stardust_diagnostic_view result = {0};
stardust_document_error(failed, &result);{:value {:code "invalid_edn"
:message "invalid EDN (Duplicate_Key) at offset 6"
:path nil
:field nil
:entity nil
:offset 6
:status "invalid_argument"}}Refuse a metadata-only transaction
patch_text holds this document:
{:#_tx {:author "x"}}stardust_document *patch = NULL;
stardust_result *failed = NULL;
uint32_t status = stardust_parse(patch_text, STARDUST_EDN, &patch);
if (status != STARDUST_OK) {stardust_document_release(patch); return status;}
status = stardust_db_merge_patch(db, patch, NULL, NULL, &failed);
stardust_document_release(patch);
stardust_diagnostic_view result = {0};
stardust_result_error(failed, &result);{:value {:code "transaction_only"
:message "a patch of only #_tx is refused: #_tx annotates a write"
:path "#_tx"
:field nil
:entity nil
:offset nil
:status "rejected"}}Refuse a repeated commit time
future_text holds this document:
{:#_d {:x 1}
:#_tx {:stardust/committedAt #inst "2200-01-01T00:00:00Z"}}patch_text holds this document:
{:#_e {:x 2}
:#_tx {:stardust/committedAt #inst "2200-01-01T00:00:00Z"}}stardust_document *future = NULL;
stardust_document *patch = NULL;
stardust_result *committed = NULL;
uint32_t status = stardust_parse(future_text, STARDUST_EDN, &future);
if (status == STARDUST_OK) status = stardust_parse(patch_text, STARDUST_EDN, &patch);
if (status == STARDUST_OK) status = stardust_db_merge_patch(db, future, NULL, NULL, &committed);
stardust_result_release(committed);
stardust_document_release(future);
if (status != STARDUST_OK) {stardust_document_release(patch); return status;}
stardust_result *failed = NULL;
status = stardust_db_merge_patch(db, patch, NULL, NULL, &failed);
stardust_document_release(patch);
stardust_diagnostic_view result = {0};
stardust_result_error(failed, &result);{:value {:code "invalid_commit_time"
:message "stardust/committedAt must be strictly newer than the latest commit time"
:path nil
:field nil
:entity nil
:offset nil
:status "invalid_commit_time"}}Refuse an invalid query definition
definition_text holds this document:
{:find [?x]}stardust_document *definition = NULL;
uint32_t status = stardust_parse(definition_text, STARDUST_EDN, &definition);
if (status != STARDUST_OK) {stardust_document_release(definition); return status;}
stardust_db_source source = {.kind = STARDUST_SOURCE_DOCUMENT, .document = definition};
stardust_db_query *failed = NULL;
status = stardust_db_query_open(db, &source, &failed);
stardust_document_release(definition);
stardust_diagnostic_view result = {0};
stardust_db_query_error(failed, &result);{:value {:code "unbound_variable"
:message "Unbound_Variable"
:path nil
:field nil
:entity nil
:offset nil
:status "invalid_definition"}}Report a missing stored query
stardust_db_source source = {.kind = STARDUST_SOURCE_PATH, .path = {(const uint8_t *)"people/missing", 14}};
stardust_db_query *failed = NULL;
uint32_t status = stardust_db_query_open(db, &source, &failed);
stardust_diagnostic_view result = {0};
stardust_db_query_error(failed, &result);{:value {:code "not_found"
:message "no definition at this path"
:path "people/missing"
:field nil
:entity nil
:offset nil
:status "not_found"}}Report a malformed byte at offset zero
malformed_text holds these bytes:
]
stardust_document *failed = NULL;
uint32_t status = stardust_parse(malformed_text, STARDUST_DUST, &failed);
stardust_diagnostic_view result = {0};
stardust_document_error(failed, &result);{:value {:code "invalid_dust"
:message "Invalid_Syntax at offset 0"
:path nil
:field nil
:entity nil
:offset 0
:status "invalid_argument"}}Report malformed DUST
malformed_text holds these bytes:
[
stardust_document *failed = NULL;
uint32_t status = stardust_parse(malformed_text, STARDUST_DUST, &failed);
stardust_diagnostic_view result = {0};
stardust_document_error(failed, &result);{:value {:code "invalid_dust"
:message "Unexpected_End at offset 2"
:path nil
:field nil
:entity nil
:offset 2
:status "invalid_argument"}}