Storine v0.3.0

Reference

Errors

Every status a server can answer, what each client calls it, and which ones to retry.

Statuses#

CodeNameMeaningWhat to do
0x00OkSuccess
0x01NotFoundThe document does not exist (or a patched document did not)Not an error for get, which returns nothing
0x02ErrorA server-side failure, such as an I/O error. The message says whatLook at the server; retry if it was transient
0x03OverloadedToo many connections, or too many analytic queries or admin jobs at onceRetry later, with backoff. Clients do this for analytics
0x04ConflictA precondition failed. Carries the index of the failed write, whether the document exists, and its current versionRead again, then decide
0x05UnauthorizedNo token, a wrong token, or a role too low for the request. The connection is closedFix the token or the role
0x06RateLimitedThis connection exceeded STORAGE_RATE_LIMIT. The connection is closedRetry later
0x07NotLeaderA cluster follower got a request for the leader. Carries the leader's address, or nothing if it is not known yetClients retry on the leader by themselves
0x08InvalidA malformed request, a bad value, a type mismatch, a crossed min or max, a limit exceededDo not retry: fix the request
0x09CommitUnknownA replicated write could not be confirmed within 5 seconds. It may still commitClients retry with the same request id, so it is applied once

A request rejected before its body was read (unauthorized, too large, rate limited) gets its error, and then the server closes the connection.

In each client#

StatusPython, RubyTypeScriptGoJava, C#, PHPRust
NotFoundNotFoundErrorNotFoundErrorErrNotFoundNotFoundExceptionError::NotFound
ConflictConflictErrorConflictErrorErrConflictConflictExceptionError::Conflict
InvalidInvalidErrorInvalidErrorErrInvalidInvalidExceptionError::Invalid
UnauthorizedUnauthorizedErrorUnauthorizedErrorErrUnauthorizedUnauthorizedExceptionError::Unauthorized
OverloadedOverloadedErrorOverloadedErrorErrOverloadedOverloadedExceptionError::Overloaded
RateLimitedRateLimitedErrorRateLimitedErrorErrRateLimitedRateLimitedExceptionError::RateLimited
no server reachableUnavailableErrorUnavailableErrorErrUnavailableUnavailableExceptionError::Unavailable
ErrorServerErrorServerErrorErrServerServerExceptionError::Server

Every error derives from one base: StorineError (Python, TypeScript), Storine::Error (Ruby), *storine.Error with errors.Is (Go), StorineException (Java, C#, PHP) and storine::Error (Rust, where is_retryable() says which may succeed later). A conflict carries the failed write's index and the current version: write_index and current_version in Python and Ruby, writeIndex and currentVersion elsewhere.

NotLeader and CommitUnknown never reach your code: the clients handle them.

Common messages#

MessageCause
refusing to serve without authentication on a non-loopback addressThe server was given a network address without STORAGE_AUTH_TOKENS
STORAGE_AUTH_TOKENS entries must be token:roleA malformed token list. Roles are read, write, admin
STORAGE_CLUSTER_TOKEN must be at least 16 charactersThe node-to-node token is too short
--peers must list this node's own --node-idEach node must appear in its own --peers
range clusters with authentication need STORAGE_CLUSTER_TOKENSet the node token on every range node
backup name must be a relative path without '..', ':' or '\'A remote backup name tried to leave the backup root

More symptoms and fixes are in troubleshooting.