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:

TRON

24 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	BC 7B3A612031203A 6120327D	txt "{:a 1 :a 2}"
10	04000000 00000000	root → @4; previous: none

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

TRON

254 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	6C 737461747573	txt "status"
0B	14 10 696E76616C69 645F617267756D65 6E74	txt "invalid_argument"
1D	0F 0A 04000000 0B00 0000	map leaf, size 10: @4 → @B
27	6C 656E74697479	txt "entity"
2E	00	nil
2F	0F 0A 27000000 2E00 0000	map leaf, size 10: @27 → @2E
39	7C 6D657373616765	txt "message"
41	14 27 696E76616C69 642045444E202844 75706C6963617465 5F4B657929206174 206F666673657420 36	txt "invalid EDN (Duplicate_K…"
6A	0F 0A 39000000 4100 0000	map leaf, size 10: @39 → @41
74	07 0E 08020000 2F00 0000 6A000000	map branch, size 14, depth 1, slots 3, 9: @2F → @6A
82	4C 70617468	txt "path"
87	00	nil
88	0F 0A 82000000 8700 0000	map leaf, size 10: @82 → @87
92	5C 6669656C64	txt "field"
98	00	nil
99	0F 0A 92000000 9800 0000	map leaf, size 10: @92 → @98
A3	4C 636F6465	txt "code"
A8	BC 696E76616C6964 5F65646E	txt "invalid_edn"
B4	0F 0A A3000000 A800 0000	map leaf, size 10: @A3 → @A8
BE	6C 6F6666736574	txt "offset"
C5	02 06000000000000 00	i64 6
CE	0F 0A BE000000 C500 0000	map leaf, size 10: @BE → @C5
D8	07 1E 51620000 1D00 0000 74000000 8800 0000 99000000 B400 0000 CE000000	map branch, size 30, depth 0 (root), slots 0, 4, 6, 9, 13, 14: @1D → @74 → @88 → @99 → @B4 → @CE
F6	D8000000 00000000	root → @D8; previous: none

Refuse a metadata-only transaction

patch_text holds this document:

TRON

46 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	6C 617574686F72	txt "author"
0B	1C 78	txt "x"
0D	0F 0A 04000000 0B00 0000	map leaf, size 10: @4 → @B
17	4C 235F7478	txt "#_tx"
1C	0F 0A 17000000 0D00 0000	map leaf, size 10: @17 → @D
26	1C000000 00000000	root → @1C; previous: none

390 B

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

TRON

263 B

Offset (hex)	Bytes (hex)	Meaning
000	54 52 4F 4E	magic TRON
004	6C 737461747573	txt "status"
00B	8C 72656A65637465 64	txt "rejected"
014	0F 0A 04000000 0B00 0000	map leaf, size 10: @4 → @B
01E	6C 656E74697479	txt "entity"
025	00	nil
026	0F 0A 1E000000 2500 0000	map leaf, size 10: @1E → @25
030	7C 6D657373616765	txt "message"
038	14 37 612070617463 68206F66206F6E6C 7920235F74782069 7320726566757365 643A20235F747820 616E6E6F74617465 7320612077726974 65	txt "a patch of only #_tx is …"
071	0F 0A 30000000 3800 0000	map leaf, size 10: @30 → @38
07B	07 0E 08020000 2600 0000 71000000	map branch, size 14, depth 1, slots 3, 9: @26 → @71
089	4C 70617468	txt "path"
08E	4C 235F7478	txt "#_tx"
093	0F 0A 89000000 8E00 0000	map leaf, size 10: @89 → @8E
09D	5C 6669656C64	txt "field"
0A3	00	nil
0A4	0F 0A 9D000000 A300 0000	map leaf, size 10: @9D → @A3
0AE	4C 636F6465	txt "code"
0B3	14 10 7472616E7361 6374696F6E5F6F6E 6C79	txt "transaction_only"
0C5	0F 0A AE000000 B300 0000	map leaf, size 10: @AE → @B3
0CF	6C 6F6666736574	txt "offset"
0D6	00	nil
0D7	0F 0A CF000000 D600 0000	map leaf, size 10: @CF → @D6
0E1	07 1E 51620000 1400 0000 7B000000 9300 0000 A4000000 C500 0000 D7000000	map branch, size 30, depth 0 (root), slots 0, 4, 6, 9, 13, 14: @14 → @7B → @93 → @A4 → @C5 → @D7
0FF	E1000000 00000000	root → @E1; previous: none

Refuse a repeated commit time

future_text holds this document:

TRON

145 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	1C 78	txt "x"
06	02 01000000000000 00	i64 1
0F	0F 0A 04000000 0600 0000	map leaf, size 10: @4 → @6
19	4C 23757463	txt "#utc"
1E	14 14 323230302D30 312D30315430303A 30303A30305A	txt "2200-01-01T00:00:00Z"
34	0F 0A 19000000 1E00 0000	map leaf, size 10: @19 → @1E
3E	14 14 737461726475 73742F636F6D6D69 747465644174	txt "stardust/committedAt"
54	0F 0A 3E000000 3400 0000	map leaf, size 10: @3E → @34
5E	4C 235F7478	txt "#_tx"
63	0F 0A 5E000000 5400 0000	map leaf, size 10: @5E → @54
6D	3C 235F64	txt "#_d"
71	0F 0A 6D000000 0F00 0000	map leaf, size 10: @6D → @F
7B	07 0E 08010000 6300 0000 71000000	map branch, size 14, depth 0 (root), slots 3, 8: @63 → @71
89	7B000000 00000000	root → @7B; previous: none

patch_text holds this document:

TRON

145 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	1C 78	txt "x"
06	02 02000000000000 00	i64 2
0F	0F 0A 04000000 0600 0000	map leaf, size 10: @4 → @6
19	4C 23757463	txt "#utc"
1E	14 14 323230302D30 312D30315430303A 30303A30305A	txt "2200-01-01T00:00:00Z"
34	0F 0A 19000000 1E00 0000	map leaf, size 10: @19 → @1E
3E	14 14 737461726475 73742F636F6D6D69 747465644174	txt "stardust/committedAt"
54	0F 0A 3E000000 3400 0000	map leaf, size 10: @3E → @34
5E	4C 235F7478	txt "#_tx"
63	0F 0A 5E000000 5400 0000	map leaf, size 10: @5E → @54
6D	3C 235F65	txt "#_e"
71	0F 0A 6D000000 0F00 0000	map leaf, size 10: @6D → @F
7B	07 0E 08010000 6300 0000 71000000	map branch, size 14, depth 0 (root), slots 3, 8: @63 → @71
89	7B000000 00000000	root → @7B; previous: none

716 B

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

TRON

290 B

Offset (hex)	Bytes (hex)	Meaning
000	54 52 4F 4E	magic TRON
004	6C 737461747573	txt "status"
00B	14 13 696E76616C69 645F636F6D6D6974 5F74696D65	txt "invalid_commit_time"
020	0F 0A 04000000 0B00 0000	map leaf, size 10: @4 → @B
02A	6C 656E74697479	txt "entity"
031	00	nil
032	0F 0A 2A000000 3100 0000	map leaf, size 10: @2A → @31
03C	7C 6D657373616765	txt "message"
044	14 47 737461726475 73742F636F6D6D69 747465644174206D 7573742062652073 74726963746C7920 6E65776572207468 616E20746865206C 617465737420636F 6D6D69742074696D 65	txt "stardust/committedAt mus…"
08D	0F 0A 3C000000 4400 0000	map leaf, size 10: @3C → @44
097	07 0E 08020000 3200 0000 8D000000	map branch, size 14, depth 1, slots 3, 9: @32 → @8D
0A5	4C 70617468	txt "path"
0AA	00	nil
0AB	0F 0A A5000000 AA00 0000	map leaf, size 10: @A5 → @AA
0B5	5C 6669656C64	txt "field"
0BB	00	nil
0BC	0F 0A B5000000 BB00 0000	map leaf, size 10: @B5 → @BB
0C6	4C 636F6465	txt "code"
0CB	14 13 696E76616C69 645F636F6D6D6974 5F74696D65	txt "invalid_commit_time"
0E0	0F 0A C6000000 CB00 0000	map leaf, size 10: @C6 → @CB
0EA	6C 6F6666736574	txt "offset"
0F1	00	nil
0F2	0F 0A EA000000 F100 0000	map leaf, size 10: @EA → @F1
0FC	07 1E 51620000 2000 0000 97000000 AB00 0000 BC000000 E000 0000 F2000000	map branch, size 30, depth 0 (root), slots 0, 4, 6, 9, 13, 14: @20 → @97 → @AB → @BC → @E0 → @F2
11A	FC000000 00000000	root → @FC; previous: none

Refuse an invalid query definition

definition_text holds this document:

TRON

43 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	2C 3F78	txt "?x"
07	0E 0D 00 0100 010000 00 04000000	array leaf, size 13, shift 0, bitmap 0001, count 1 (root): @4
14	4C 66696E64	txt "find"
19	0F 0A 14000000 0700 0000	map leaf, size 10: @14 → @7
23	19000000 00000000	root → @19; previous: none

496 B

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

TRON

231 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	6C 737461747573	txt "status"
0B	14 12 696E76616C69 645F646566696E69 74696F6E	txt "invalid_definition"
1F	0F 0A 04000000 0B00 0000	map leaf, size 10: @4 → @B
29	6C 656E74697479	txt "entity"
30	00	nil
31	0F 0A 29000000 3000 0000	map leaf, size 10: @29 → @30
3B	7C 6D657373616765	txt "message"
43	14 10 556E626F756E 645F566172696162 6C65	txt "Unbound_Variable"
55	0F 0A 3B000000 4300 0000	map leaf, size 10: @3B → @43
5F	07 0E 08020000 3100 0000 55000000	map branch, size 14, depth 1, slots 3, 9: @31 → @55
6D	4C 70617468	txt "path"
72	00	nil
73	0F 0A 6D000000 7200 0000	map leaf, size 10: @6D → @72
7D	5C 6669656C64	txt "field"
83	00	nil
84	0F 0A 7D000000 8300 0000	map leaf, size 10: @7D → @83
8E	4C 636F6465	txt "code"
93	14 10 756E626F756E 645F766172696162 6C65	txt "unbound_variable"
A5	0F 0A 8E000000 9300 0000	map leaf, size 10: @8E → @93
AF	6C 6F6666736574	txt "offset"
B6	00	nil
B7	0F 0A AF000000 B600 0000	map leaf, size 10: @AF → @B6
C1	07 1E 51620000 1F00 0000 5F000000 7300 0000 84000000 A500 0000 B7000000	map branch, size 30, depth 0 (root), slots 0, 4, 6, 9, 13, 14: @1F → @5F → @73 → @84 → @A5 → @B7
DF	C1000000 00000000	root → @C1; previous: none

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

TRON

237 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	6C 737461747573	txt "status"
0B	9C 6E6F745F666F75 6E64	txt "not_found"
15	0F 0A 04000000 0B00 0000	map leaf, size 10: @4 → @B
1F	6C 656E74697479	txt "entity"
26	00	nil
27	0F 0A 1F000000 2600 0000	map leaf, size 10: @1F → @26
31	7C 6D657373616765	txt "message"
39	14 1A 6E6F20646566 696E6974696F6E20 6174207468697320 70617468	txt "no definition at this pa…"
55	0F 0A 31000000 3900 0000	map leaf, size 10: @31 → @39
5F	07 0E 08020000 2700 0000 55000000	map branch, size 14, depth 1, slots 3, 9: @27 → @55
6D	4C 70617468	txt "path"
72	EC 70656F706C652F 6D697373696E67	txt "people/missing"
81	0F 0A 6D000000 7200 0000	map leaf, size 10: @6D → @72
8B	5C 6669656C64	txt "field"
91	00	nil
92	0F 0A 8B000000 9100 0000	map leaf, size 10: @8B → @91
9C	4C 636F6465	txt "code"
A1	9C 6E6F745F666F75 6E64	txt "not_found"
AB	0F 0A 9C000000 A100 0000	map leaf, size 10: @9C → @A1
B5	6C 6F6666736574	txt "offset"
BC	00	nil
BD	0F 0A B5000000 BC00 0000	map leaf, size 10: @B5 → @BC
C7	07 1E 51620000 1500 0000 5F000000 8100 0000 92000000 AB00 0000 BD000000	map branch, size 30, depth 0 (root), slots 0, 4, 6, 9, 13, 14: @15 → @5F → @81 → @92 → @AB → @BD
E5	C7000000 00000000	root → @C7; previous: none

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

TRON

242 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	6C 737461747573	txt "status"
0B	14 10 696E76616C69 645F617267756D65 6E74	txt "invalid_argument"
1D	0F 0A 04000000 0B00 0000	map leaf, size 10: @4 → @B
27	6C 656E74697479	txt "entity"
2E	00	nil
2F	0F 0A 27000000 2E00 0000	map leaf, size 10: @27 → @2E
39	7C 6D657373616765	txt "message"
41	14 1A 496E76616C69 645F53796E746178 206174206F666673 65742030	txt "Invalid_Syntax at offset…"
5D	0F 0A 39000000 4100 0000	map leaf, size 10: @39 → @41
67	07 0E 08020000 2F00 0000 5D000000	map branch, size 14, depth 1, slots 3, 9: @2F → @5D
75	4C 70617468	txt "path"
7A	00	nil
7B	0F 0A 75000000 7A00 0000	map leaf, size 10: @75 → @7A
85	5C 6669656C64	txt "field"
8B	00	nil
8C	0F 0A 85000000 8B00 0000	map leaf, size 10: @85 → @8B
96	4C 636F6465	txt "code"
9B	CC 696E76616C6964 5F64757374	txt "invalid_dust"
A8	0F 0A 96000000 9B00 0000	map leaf, size 10: @96 → @9B
B2	6C 6F6666736574	txt "offset"
B9	02 00000000000000 00	i64 0
C2	0F 0A B2000000 B900 0000	map leaf, size 10: @B2 → @B9
CC	07 1E 51620000 1D00 0000 67000000 7B00 0000 8C000000 A800 0000 C2000000	map branch, size 30, depth 0 (root), slots 0, 4, 6, 9, 13, 14: @1D → @67 → @7B → @8C → @A8 → @C2
EA	CC000000 00000000	root → @CC; previous: none

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

TRON

242 B

Offset (hex)	Bytes (hex)	Meaning
00	54 52 4F 4E	magic TRON
04	6C 737461747573	txt "status"
0B	14 10 696E76616C69 645F617267756D65 6E74	txt "invalid_argument"
1D	0F 0A 04000000 0B00 0000	map leaf, size 10: @4 → @B
27	6C 656E74697479	txt "entity"
2E	00	nil
2F	0F 0A 27000000 2E00 0000	map leaf, size 10: @27 → @2E
39	7C 6D657373616765	txt "message"
41	14 1A 556E65787065 637465645F456E64 206174206F666673 65742032	txt "Unexpected_End at offset…"
5D	0F 0A 39000000 4100 0000	map leaf, size 10: @39 → @41
67	07 0E 08020000 2F00 0000 5D000000	map branch, size 14, depth 1, slots 3, 9: @2F → @5D
75	4C 70617468	txt "path"
7A	00	nil
7B	0F 0A 75000000 7A00 0000	map leaf, size 10: @75 → @7A
85	5C 6669656C64	txt "field"
8B	00	nil
8C	0F 0A 85000000 8B00 0000	map leaf, size 10: @85 → @8B
96	4C 636F6465	txt "code"
9B	CC 696E76616C6964 5F64757374	txt "invalid_dust"
A8	0F 0A 96000000 9B00 0000	map leaf, size 10: @96 → @9B
B2	6C 6F6666736574	txt "offset"
B9	02 02000000000000 00	i64 2
C2	0F 0A B2000000 B900 0000	map leaf, size 10: @B2 → @B9
CC	07 1E 51620000 1D00 0000 67000000 7B00 0000 8C000000 A800 0000 C2000000	map branch, size 30, depth 0 (root), slots 0, 4, 6, 9, 13, 14: @1D → @67 → @7B → @8C → @A8 → @C2
EA	CC000000 00000000	root → @CC; previous: none