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

When Operations

native memory is exhausted stardust_db_read_entity, stardust_parse, stardust_serialize, stardust_document_builder_create, stardust_document_builder_add_many, stardust_document_builder_seal, stardust_expr_build, stardust_macro_build, stardust_macro_expand, stardust_expr_evaluate, stardust_db_open, stardust_db_query_open, stardust_db_mutation_open, stardust_db_expression_build, stardust_db_query_run, stardust_db_rows_next, stardust_db_query_subscribe, stardust_db_subscription_next, stardust_db_mutation_run, stardust_db_merge_patch, stardust_db_definition_get, stardust_db_plan, stardust_db_definition_list, stardust_db_definition_patch, stardust_db_bulk_begin, stardust_db_bulk_add, stardust_db_bulk_finish, stardust_db_plugin_call, stardust_db_plugin_stream_open, stardust_db_plugin_stream_finish, stardust_plugins

When	Operations
native memory is exhausted	`stardust_db_read_entity`, `stardust_parse`, `stardust_serialize`, `stardust_document_builder_create`, `stardust_document_builder_add_many`, `stardust_document_builder_seal`, `stardust_expr_build`, `stardust_macro_build`, `stardust_macro_expand`, `stardust_expr_evaluate`, `stardust_db_open`, `stardust_db_query_open`, `stardust_db_mutation_open`, `stardust_db_expression_build`, `stardust_db_query_run`, `stardust_db_rows_next`, `stardust_db_query_subscribe`, `stardust_db_subscription_next`, `stardust_db_mutation_run`, `stardust_db_merge_patch`, `stardust_db_definition_get`, `stardust_db_plan`, `stardust_db_definition_list`, `stardust_db_definition_patch`, `stardust_db_bulk_begin`, `stardust_db_bulk_add`, `stardust_db_bulk_finish`, `stardust_db_plugin_call`, `stardust_db_plugin_stream_open`, `stardust_db_plugin_stream_finish`, `stardust_plugins`

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

When Operations

the database is closed stardust_db_read_entity, stardust_db_query_open, stardust_db_mutation_open, stardust_db_expression_build, stardust_db_merge_patch, stardust_db_definition_get, stardust_db_plan, stardust_db_definition_list, stardust_db_definition_patch, stardust_db_indexes_sync, stardust_db_bulk_begin, stardust_db_bulk_add, stardust_db_bulk_finish, stardust_db_plugin_call, stardust_db_plugin_stream_open

the parent database is closed stardust_db_query_run, stardust_db_rows_next, stardust_db_query_subscribe, stardust_db_subscription_next, stardust_db_mutation_run, stardust_db_plugin_stream_write, stardust_db_plugin_stream_read, stardust_db_plugin_stream_seek, stardust_db_plugin_stream_finish

When	Operations
the database is closed	`stardust_db_read_entity`, `stardust_db_query_open`, `stardust_db_mutation_open`, `stardust_db_expression_build`, `stardust_db_merge_patch`, `stardust_db_definition_get`, `stardust_db_plan`, `stardust_db_definition_list`, `stardust_db_definition_patch`, `stardust_db_indexes_sync`, `stardust_db_bulk_begin`, `stardust_db_bulk_add`, `stardust_db_bulk_finish`, `stardust_db_plugin_call`, `stardust_db_plugin_stream_open`
the parent database is closed	`stardust_db_query_run`, `stardust_db_rows_next`, `stardust_db_query_subscribe`, `stardust_db_subscription_next`, `stardust_db_mutation_run`, `stardust_db_plugin_stream_write`, `stardust_db_plugin_stream_read`, `stardust_db_plugin_stream_seek`, `stardust_db_plugin_stream_finish`

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:

json

14 B

"{:a 1 :a 2}"

640 B

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_JSON, &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);

Result / 181 B

{
  "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:

json

38 B

{
  "#_tx": {
    "author": "x"
  }
}

390 B

stardust_document *patch = NULL;
stardust_result *failed = NULL;
uint32_t status = stardust_parse(patch_text, STARDUST_JSON, &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);

Result / 199 B

{
  "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:

json

120 B

{
  "#_d": {
    "x": 1
  },
  "#_tx": {
    "stardust/committedAt": {
      "#utc": "2200-01-01T00:00:00Z"
    }
  }
}

patch_text holds this document:

json

120 B

{
  "#_e": {
    "x": 2
  },
  "#_tx": {
    "stardust/committedAt": {
      "#utc": "2200-01-01T00:00:00Z"
    }
  }
}

716 B

stardust_document *future = NULL;
stardust_document *patch = NULL;
stardust_result *committed = NULL;
uint32_t status = stardust_parse(future_text, STARDUST_JSON, &future);
if (status == STARDUST_OK) status = stardust_parse(patch_text, STARDUST_JSON, &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);

Result / 227 B

{
  "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:

json

29 B

{
  "find": [
    "?x"
  ]
}

496 B

stardust_document *definition = NULL;
uint32_t status = stardust_parse(definition_text, STARDUST_JSON, &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);

Result / 168 B

{
  "code": "unbound_variable",
  "message": "Unbound_Variable",
  "path": null,
  "field": null,
  "entity": null,
  "offset": null,
  "status": "invalid_definition"
}

Report a missing stored query

287 B

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);

Result / 174 B

{
  "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:

text

1 B

188 B

stardust_document *failed = NULL;
uint32_t status = stardust_parse(malformed_text, STARDUST_DUST, &failed);
stardust_diagnostic_view result = {0};
stardust_document_error(failed, &result);

Result / 169 B

{
  "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:

text

1 B

188 B

stardust_document *failed = NULL;
uint32_t status = stardust_parse(malformed_text, STARDUST_DUST, &failed);
stardust_diagnostic_view result = {0};
stardust_document_error(failed, &result);

Result / 169 B

{
  "code": "invalid_dust",
  "message": "Unexpected_End at offset 2",
  "path": null,
  "field": null,
  "entity": null,
  "offset": 2,
  "status": "invalid_argument"
}