Errors
Handle Rust SDK error variants, and recover writes and commits whose outcome is unknown.
Table handles, configuration and management clients return spiral::Error.
Resource calls preserve CallError<E>, where E is the generated service error
under spiral::api. High-level clients wrap it in the corresponding
spiral::Error variant. The low-level Location, Task and Vector Index clients
return CallError<E> directly. Inspect ServiceFailure::declared() for a known
service error and status() for the observed HTTP status; unknown envelopes,
transport failures and invalid responses remain distinct. For a request whose outcome is uncertain,
recover it using the same operation identity. See
Retries.
Variants
| Variant | Meaning | What to do |
|---|---|---|
CredentialsNotFound | No configured credential source supplies credentials. | Supply a bearer token or credential provider, or configure a Workload. |
Credentials(error) | A credential source could not supply a usable credential, for example a misconfigured provider or a rejected token request. | Read the wrapped CredentialError; repair the selected credential source. |
Http(error) | An HTTP request or response failed. | Check the connection and response. |
Rejected { url, status, body } | The service rejected a request, with its HTTP status and response body. | Read the status and body; correct the request or its permissions. |
Applications(error) | Application or installation management failed. | Inspect the typed service error and observed HTTP status. |
Protocol(message) | A response violates the expected format, such as a repeated pagination token. | Report the invalid response. |
NotFound(path) | Nothing is bound at that path in the selected commit. | Check the path and the reference after @. |
InvalidConfiguration(message) | The client configuration or an argument is not valid, for example a malformed address. | Correct the configuration or the argument. |
Arbor(error) | The Tables service returned an error. | Read the service error. |
Catalog(error) | The Catalog service returned an error. | Read the service error. |
Scandal(error) | A ScanDAL operation, such as a scan, write or blob transfer, failed. | Read the wrapped error. |
Native(message) | The embedded native library failed. Exists with the embedded feature. | Read the message; check that the native archive matches your SDK release. |
Arrow(message) | Arrow data could not be encoded or decoded. | Check the input schema and batches. |
BranchMoved { current } | Another writer moved the branch after you pinned it, so the commit was not published. current is the branch's head. | Pin the branch again and redo the writes. |
Conflict(conflict) | A staged change conflicts with the branch head, for example creating a name that already exists. Nothing was published. | Change what you stage. |
OutcomeUnknown { operation_id, message } | The commit may have been published. | To recover, match PublishError::Unknown before converting it. See Unknown commit outcome. |
RegistrationUnknown { receipt, message } | The new Table version may have been registered. | Call table.recover_write(receipt) on the Table you wrote from, or client.register_prepared(receipt) for a new Table. |
Unknown commit outcome
commit.publish() returns its own error type, PublishError. The ?
operator converts it into Error: PublishError::BranchMoved and
PublishError::Conflict become the variants of the same names,
PublishError::Unknown becomes OutcomeUnknown, and PublishError::Failed
becomes the Error it wraps.
When the response is lost, publish returns PublishError::Unknown with a
FrozenCommit, which can only ever send the same request. OutcomeUnknown
keeps only the operation ID, not the frozen commit, so match
PublishError::Unknown before you convert the error if you want to recover.
recover on the frozen commit returns the new head if Spiral recorded the
commit. If it returns None, publishing the frozen commit again is safe. See
Commits.
Unknown registration outcome
RegistrationUnknown carries a receipt for the files that the write already
uploaded. The SDK consumed your Arrow input during the upload, so do not upload
it again; pass the receipt back instead. See
Writing.
A moved branch publishes nothing
When another writer moved the branch, publish returns
PublishError::BranchMoved, or Error::BranchMoved after ?, and publishes
nothing. When a staged change conflicts with the head, such as creating a name
that already exists, it returns PublishError::Conflict, or Error::Conflict.
Handle both as expected results rather than
failures: pin the branch again, or change what you stage, and redo the writes.
See
Commits.
For the error bodies of the HTTP API, see HTTP API errors.