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 | *string | None | nil |
field | *string | None | nil |
entity | *int64 | None | nil |
offset | *int64 | 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.
StatusInvalidArgument
Codes: time_out_of_range, invalid_argument, out_of_range, unsigned_value, non_finite_number, cycle, unsupported_type, too_large, native_failure, live_children.
| When | Operations |
|---|---|
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 | Document.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, a number outside i64 or finite f64, or a cycle | FromValue |
| the node breaks the preorder rules or has an invalid kind or number | Builder.Add |
| a node breaks the preorder rules or has an invalid kind or number | Builder.AddMany |
| the builder has no root or a container is still open | Builder.Seal |
| id is not a node of the document | Document.Read, Document.Children |
| start is past the last node or capacity is negative | Document.ReadMany |
| id is not an object node of the document | Document.Member, Document.Members |
| the node is not an integer number | Document.I64 |
the node is not a number or its value overflows f64 | Document.F64 |
| the arguments include an undeclared macro parameter | BuildMacro, ExpandMacro |
| the file is not a database or an option is invalid | Open |
| the parameters or run options are invalid | Query.Run, Mutation.Run |
| the parameters or subscription options are invalid | Query.Subscribe |
max_wait is negative | Subscription.Next, Database.ReactorsSync |
| the patch is not an entity-keyed object | Database.MergePatch |
| the kind or the pattern is invalid | Database.Definitions |
StatusInvalidJSON
StatusCompileFailed
| When | Operations |
|---|---|
| the expression does not compile | Build |
| the expansion does not compile | BuildMacro |
StatusEvaluationFailed
| When | Operations |
|---|---|
| the expression fails on the input | Program.Evaluate |
the query fails or exceeds max_cost | Query.Run |
| the page does not render | Rows.Next |
| a page does not render | Rows.Pages, Rows.AllPages |
| a rerun of the query failed. Every later call reports this failure | Subscription.Next |
| a rerun of the query failed | Subscription.All |
| the mutation fails | Mutation.Run |
StatusOutOfMemory
Codes: out_of_memory.
| When | Operations |
|---|---|
| native memory is exhausted | Parse, Document.Serialize, Convert, FromValue, NewBuilder, Builder.Add, Builder.AddMany, Builder.Seal, Build, BuildMacro, ExpandMacro, Program.Evaluate, Open, Database.Query, Database.Mutation, Query.Run, Rows.Next, Rows.Pages, Rows.AllPages, Query.Subscribe, Subscription.Next, Subscription.All, Mutation.Run, Database.MergePatch, Database.Definition, Database.Definitions, Database.PatchDefinition, Database.ReactorsStatus, Plugins |
StatusNotFound
Codes: not_found.
| When | Operations |
|---|---|
| the object has no member with the key | Document.Member |
| the macro refers to an unknown macro | BuildMacro, ExpandMacro |
| the parent directory is missing, or the file is missing and create is false | Open |
| no definition is stored at the path | Database.Query, Database.Mutation, Database.Definition |
| the stored query definition was deleted | Query.Run |
StatusLocked
| When | Operations |
|---|---|
another process holds the lock after lock_timeout | Open |
StatusConflict
| When | Operations |
|---|---|
| concurrent writes prevent the commit | Mutation.Run |
StatusInvalidDefinition
| When | Operations |
|---|---|
| the macro is invalid or expands recursively | BuildMacro, ExpandMacro |
| the definition is invalid | Database.Query, Database.Mutation |
| the loaded query definition is invalid | Query.Run |
| the query or its callable definitions are invalid | Query.Subscribe |
| the mutation selection or definition is invalid | Mutation.Run |
| the patched definition is invalid | Database.PatchDefinition |
StatusSchemaViolation
| When | Operations |
|---|---|
| the write breaks a schema | Mutation.Run |
StatusInvalidCommitTime
| When | Operations |
|---|---|
the #_tx commit time is not later than the last commit | Database.MergePatch |
StatusClosed
Codes: closed.
| When | Operations |
|---|---|
| the document is closed | Document.Serialize, Document.ToValue, Document.Root, Document.Count, Document.Read, Document.ReadMany, Document.Member, Document.Children, Document.Members, Document.I64, Document.F64 |
| the builder is closed | Builder.Add, Builder.AddMany, Builder.Seal |
| the program is closed | Program.Evaluate |
| the database is closed | Database.Query, Database.Mutation, Database.MergePatch, Database.Definition, Database.Definitions, Database.PatchDefinition, Database.ReactorsStatus, Database.ReactorsSync |
| the query is closed | Query.Run, Query.Subscribe |
| the rows is closed | Rows.Next, Rows.Pages, Rows.AllPages |
| the subscription is closed | Subscription.Next |
| the mutation is closed | Mutation.Run |
StatusRejected
| When | Operations |
|---|---|
| a mutation target or write guard refuses the write | Mutation.Run |
| the database refuses the patch | Database.MergePatch |
StatusUnsupported
Codes: abi_version.
| When | Operations |
|---|---|
| found differs from the ABI version of the binding | CheckVersion |
StatusCancelled
Codes: cancelled.
| When | Operations |
|---|---|
| the subscription is cancelled or closed | Subscription.Next |
StatusTimeout
| When | Operations |
|---|---|
max_wait passed first | Database.ReactorsSync |
StatusUnavailable
| When | Operations |
|---|---|
| the database does not enable the reactors plugin | Database.ReactorsStatus, Database.ReactorsSync |
StatusFailed
| When | Operations |
|---|---|
a live mutation failure stands. reactors_status describes it | Database.ReactorsSync |
Refusal examples
The generator captured each result from the native library.
convert
duplicateText holds this document:
'{:a 1 :a 2}'
source, err := stardust.Parse(duplicateText, stardust.DUST)
if err != nil {
return err
}
defer source.Close()
root, err := source.Root()
if err != nil {
return err
}
view, err := source.Read(root)
if err != nil {
return err
}
failed, result := stardust.Parse([]byte(view.Text), stardust.EDN)
if failed != nil {
defer failed.Close()
}{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
patchText holds this document:
#_tx {author x}
patch, err := stardust.Parse(patchText, stardust.DUST)
if err != nil {
return err
}
defer patch.Close()
_, result := db.MergePatch(patch, nil){code invalid
message the write is invalid: check entity ids, field names, values and #_tx (a patch of only #_tx is refused)
path null
field null
entity null
offset null
status rejected}Refuse a repeated commit time
futureText holds this document:
#_d {x 1}
#_tx {stardust/committedAt {#utc 2200-01-01T00:00:00Z}}
patchText holds this document:
#_e {x 2}
#_tx {stardust/committedAt {#utc 2200-01-01T00:00:00Z}}
future, err := stardust.Parse(futureText, stardust.DUST)
if err != nil {
return err
}
defer future.Close()
if _, err := db.MergePatch(future, nil); err != nil {
return err
}
patch, err := stardust.Parse(patchText, stardust.DUST)
if err != nil {
return err
}
defer patch.Close()
_, result := db.MergePatch(patch, nil){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
queryText holds this document:
find [?x]
definition, err := stardust.Parse(queryText, stardust.DUST)
if err != nil {
return err
}
defer definition.Close()
query, result := db.Query(definition)
if query != nil {
defer query.Close()
}{code unbound_variable
message Unbound_Variable
path null
field null
entity null
offset null
status invalid_definition}Report a missing stored query
query, result := db.QueryPath("people/missing")
if query != nil {
defer query.Close()
}{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
malformedText holds these bytes:
]
failed, result := stardust.Parse(malformedText, stardust.DUST)
if failed != nil {
defer failed.Close()
}{code invalid_dust
message Invalid_Syntax at offset 0
path null
field null
entity null
offset 0
status invalid_argument}Report malformed DUST
malformedText holds these bytes:
[
failed, err := stardust.Parse(malformedText, stardust.DUST)
if failed != nil {
defer failed.Close()
}
var result *stardust.Error
if !errors.As(err, &result) {
return err
}{code invalid_dust
message Unexpected_End at offset 2
path null
field null
entity null
offset 2
status invalid_argument}