XMTP error code glossary
This document lists all error codes defined in LibXMTP, the core library underlying the XMTP SDKs. Each error code is a unique identifier returned to help diagnose issues.
38 error types across 10 crates with 403 total error codes.
mobile
Section titled “mobile”GenericError enum
Section titled “GenericError enum”bindings/mobile/src/lib.rs
| Error Code | Description |
|---|---|
GenericError::Generic | Generic error. Unclassified error with string message. May be retryable. |
GenericError::FailedToConvertToU32 | Failed to convert to u32. Numeric conversion failed. Not retryable. |
GenericError::JoinError | Join error. Tokio task join failed. Not retryable. |
GenericError::IoError | I/O error. File or network I/O failed. May be retryable. |
GenericError::Log | Log error. Error initializing debug log file. Not retryable. |
GenericError::Expired | Timer expired. Operation timed out. Retryable. |
GenericError::BackendBuilder | Backend configuration failed. This error is not retryable. |
GenericError::Level | Log Level failed to parse because it was invalid |
BackendBuilderError struct
Section titled “BackendBuilderError struct”bindings/node/src/client/backend.rs
Backend configuration failed. This error is not retryable.
Error code: BackendBuilderError
BackendBuilderError struct
Section titled “BackendBuilderError struct”bindings/wasm/src/client/backend.rs
Backend configuration failed. This error is not retryable.
Error code: BackendBuilderError
ContentTypeError enum
Section titled “ContentTypeError enum”bindings/wasm/src/content_types/mod.rs
Error type for content type conversion failures in WASM bindings.
Provides structured error codes via ErrorCode derive, ensuring
all content type errors are prefixed with [ContentTypeError::Variant]
when surfaced to JavaScript.
| Error Code | Description |
|---|---|
ContentTypeError::InvalidData | Invalid data. Content type data failed validation. Not retryable. |
ContentTypeError::TimestampOutOfRange | Timestamp out of range. Timestamp value is outside the representable range. Not retryable. |
ContentTypeError::Codec | Codec error. Content type codec encoding or decoding failed. Not retryable. |
ContentTypeError::Crypto | Crypto error. Cryptographic operation for content type failed. Not retryable. |
xmtp_api
Section titled “xmtp_api”ApiError enum
Section titled “ApiError enum”crates/xmtp_api/src/lib.rs
| Error Code | Description |
|---|---|
ApiError::Api | API client error. API operation error (network, deserialization, or other). May be retryable. |
ApiError::IdentityUpdateConflict | The backend rejected a stale identity update. Not retryable here. |
ApiError::EnvelopeTooLarge | One envelope exceeds the configured byte limit. Not retryable. |
ApiError::UnitTooLarge | One atomic publish unit exceeds a request limit. Not retryable. |
ApiError::ResponseTooLarge | A single-topic response still exceeds a backend limit. Not retryable. |
ApiError::InvalidRequest | The request has invalid input. Not retryable. |
ApiError::InvalidResponse | A response does not match the request. Not retryable. |
ApiError::InvalidEnvelope | The payload cannot be parsed. Not retryable. |
ApiError::Envelope | A returned backend envelope cannot be decoded. Not retryable. |
ApiError::ProtoConversion | Proto conversion error. Protobuf conversion failed. Not retryable. |
xmtp_api_grpc
Section titled “xmtp_api_grpc”GrpcBuilderError enum
Section titled “GrpcBuilderError enum”crates/xmtp_api_grpc/src/error.rs
| Error Code | Description |
|---|---|
GrpcBuilderError::MissingAppVersion | Missing app version. App version not set on builder. Not retryable. |
GrpcBuilderError::MissingLibxmtpVersion | Missing LibXMTP version. Core library version not set. Not retryable. |
GrpcBuilderError::MissingHostUrl | Missing host URL. Host URL not set on builder. Not retryable. |
GrpcBuilderError::Metadata | Metadata error. Invalid gRPC metadata value. Not retryable. |
GrpcBuilderError::InvalidUri | Invalid URI. URI is malformed. Not retryable. |
GrpcBuilderError::Url | URL parse error. URL string is malformed. Not retryable. |
GrpcBuilderError::Transport | Transport error. gRPC transport creation failed (native only). Not retryable. |
GrpcError enum
Section titled “GrpcError enum”crates/xmtp_api_grpc/src/error.rs
| Error Code | Description |
|---|---|
GrpcError::InvalidUri | Invalid URI. URI for channel creation is malformed. Not retryable. |
GrpcError::Metadata | Metadata error. Invalid gRPC metadata value. Not retryable. |
GrpcError::Status | gRPC status error. Retryability depends on the gRPC status code. |
GrpcError::NotFound | Not found. Requested resource not found, empty, or proto conversion failed. Not retryable. |
GrpcError::UnexpectedPayload | Unexpected payload. Payload not expected in response. Not retryable. |
GrpcError::MissingPayload | Missing payload. Expected payload not in response. Not retryable. |
GrpcError::Decode | Decode error. Protobuf decoding failed. Not retryable. |
GrpcError::Unreachable | Unreachable. Infallible error. Not retryable. |
GrpcError::Transport | Transport error. gRPC transport layer error (native only). Retryable. |
xmtp_db
Section titled “xmtp_db”ConnectionError enum
Section titled “ConnectionError enum”crates/xmtp_db/src/encrypted_store/mod.rs
| Error Code | Description |
|---|---|
ConnectionError::Database | Database error. Diesel database query error. May be retryable. |
ConnectionError::DecodeError | Decode error. Protobuf decode failed within DB layer. Not retryable. |
ConnectionError::DisconnectInTransaction | Disconnect in transaction. Cannot disconnect while transaction is active. Retryable. |
ConnectionError::ReconnectInTransaction | Reconnect in transaction. Cannot reconnect while transaction is active. Retryable. |
ConnectionError::InvalidQuery | Invalid query. Invalid query parameters or configuration. Not retryable. |
ConnectionError::InvalidVersion | Invalid version. DB migration version mismatch — running a newer DB on older LibXMTP. Not retryable. |
NotFound enum
Section titled “NotFound enum”crates/xmtp_db/src/errors.rs
| Error Code | Description |
|---|---|
NotFound::KeyPackageHistory | The local key package history row no longer exists. |
NotFound::GroupByWelcome | Group with welcome ID not found. No group matches the welcome ID. Retryable. |
NotFound::GroupById | Group with ID not found. Group does not exist in local DB. Retryable. |
NotFound::InstallationTimeForGroup | Installation time for group not found. Missing installation timestamp. Retryable. |
NotFound::InboxIdForAddress | Inbox ID for address not found. Address has no associated inbox. Retryable. |
NotFound::MessageById | Message ID not found. Message does not exist in local DB. Retryable. |
NotFound::DmByInbox | DM by inbox ID not found. No DM conversation with this inbox. Retryable. |
NotFound::IntentForToPublish | Intent for ToPublish not found. Failed to transition intent from ToPublish to Published. Retryable. |
NotFound::IntentForPublish | Intent for Published not found. Intent with specified ID not in expected state. Retryable. |
NotFound::IntentForCommitted | Intent for Committed not found. Failed to transition intent from Published to Committed. Retryable. |
NotFound::IntentById | Intent by ID not found. Intent does not exist. Retryable. |
NotFound::CipherSalt | Cipher salt not found. Database encryption salt missing. Retryable. |
NotFound::SyncGroup | Sync group not found. No sync group for this installation. Retryable. |
NotFound::KeyPackageReference | Key package reference not found. Key package handle not in store. Retryable. |
NotFound::MlsGroup | MLS group not found. OpenMLS group not in local state. Retryable. |
NotFound::PostQuantumPrivateKey | Post-quantum private key not found. PQ key pair not in store. Retryable. |
NotFound::KeyPackage | Key package not found. Key package not in store. Retryable. |
PlatformStorageError enum
Section titled “PlatformStorageError enum”crates/xmtp_db/src/encrypted_store/database/native.rs
| Error Code | Description |
|---|---|
PlatformStorageError::Pool | Pool error. Database connection pool error. Retryable. |
PlatformStorageError::DbConnection | DB connection error. R2D2 connection manager error (e.g. a failed on_acquire while establishing a connection). Transient — retryable. |
PlatformStorageError::PoolNeedsConnection | Pool needs connection. Pool must reconnect before use. Retryable. |
PlatformStorageError::PoolRequiresPath | Pool requires path. DB pool requires a persistent file path. Not retryable. |
PlatformStorageError::SqlCipherNotLoaded | SQLCipher not loaded. Encryption key given but SQLCipher not available. Retryable. |
PlatformStorageError::SqlCipherKeyIncorrect | SQLCipher key incorrect. PRAGMA key or salt has wrong value. Not retryable. |
PlatformStorageError::DatabaseLocked | Database locked. Database file is locked by another process. Retryable. |
PlatformStorageError::DieselResult | Diesel result error. Database query error. May be retryable. |
PlatformStorageError::NotFound | Not found. Record not found in storage. Not retryable. |
PlatformStorageError::Io | I/O error. File system I/O error. Retryable. |
PlatformStorageError::FromHex | Hex decode error. Failed to decode hex string. Not retryable. |
PlatformStorageError::DieselConnect | Diesel connection error. Failed to establish connection. Retryable. |
PlatformStorageError::Boxed | Boxed error. Wrapped dynamic error. Not retryable. |
PlatformStorageError enum
Section titled “PlatformStorageError enum”crates/xmtp_db/src/encrypted_store/database/wasm.rs
| Error Code | Description |
|---|---|
PlatformStorageError::SAH | OPFS error. Origin Private File System (OPFS) error. Retryable. |
PlatformStorageError::Connection | Connection error. Diesel connection error. Retryable. |
PlatformStorageError::DieselResult | Diesel result error. Database query error. Retryable. |
PlatformStorageError::Disconnected | The persistent connection was closed. Reconnect before using it. |
PlatformStorageError::Replaced | The file was restored or deleted. This object cannot reconnect. |
PlatformStorageError::DatabaseInUse | A target connection is still open or has an active query. |
PlatformStorageError::RestoreDestinationExists | Whole-database import does not replace an existing OPFS file. |
PlatformStorageError::InvalidRestoreInput | The restore input is not a complete SQLite database. |
PlatformStorageError::Initialization | The OPFS utility could not be initialized. |
SqlKeyStoreError enum
Section titled “SqlKeyStoreError enum”crates/xmtp_db/src/sql_key_store.rs
Errors thrown by the key store. General error type for Mls Storage Trait
| Error Code | Description |
|---|---|
SqlKeyStoreError::UnsupportedValueTypeBytes | Unsupported value type. Key store does not allow storing serialized values. Not retryable. |
SqlKeyStoreError::UnsupportedMethod | Unsupported method. PSK operations not supported by this key store. Not retryable. |
SqlKeyStoreError::SerializationError | Serialization error. Failed to serialize value for key store. Not retryable. |
SqlKeyStoreError::NotFound | Value not found. Requested key not in OpenMLS key store. Not retryable. |
SqlKeyStoreError::Storage | Database error. Underlying Diesel database error. May be retryable. |
SqlKeyStoreError::Connection | Connection error. Database connection error. Retryable. |
StorageError enum
Section titled “StorageError enum”crates/xmtp_db/src/errors.rs
| Error Code | Description |
|---|---|
StorageError::PreTransitionDatabase | The database was created before the backend transition. Not retryable. |
StorageError::OldStreamDatabase | The database uses the previous self-hosted stream format. |
StorageError::DieselConnect | Diesel connection error. Failed to connect to SQLite. Retryable. |
StorageError::DieselResult | Diesel result error. Database query returned an error. May be retryable. |
StorageError::MigrationError | Migration error. Database migration failed. Not retryable. |
StorageError::NotFound | Not found. Requested record does not exist. Not retryable. |
StorageError::Duplicate | Duplicate item. Attempted to insert a duplicate record. Not retryable. |
StorageError::OpenMlsStorage | OpenMLS storage error. OpenMLS key store operation failed. Not retryable. |
StorageError::DbDeserialize | DB deserialization failed. Failed to deserialize data from database. Not retryable. |
StorageError::DbSerialize | DB serialization failed. Failed to serialize data for database. Not retryable. |
StorageError::Builder | Builder error. Required fields missing from stored type. Not retryable. |
StorageError::Platform | Platform storage error. Platform-specific storage error. May be retryable. |
StorageError::Prost | Protobuf decode error. Failed to decode protobuf from database. Not retryable. |
StorageError::Conversion | Conversion error. Proto conversion failed. Not retryable. |
StorageError::Connection | Connection error. Database connection error. Retryable. |
StorageError::InvalidHmacLength | Invalid HMAC length. HMAC key must be 42 bytes. Not retryable. |
StorageError::GroupIntent | Group intent error. Group intent processing failed. May be retryable. |
StreamStorageError enum
Section titled “StreamStorageError enum”crates/xmtp_db/src/encrypted_store/stream_storage.rs
Stable storage failures that preserve receipt, processing, and delivery invariants.
| Error Code | Description |
|---|---|
StreamStorageError::InvalidBatch | The batch does not have valid, strictly increasing envelope IDs. |
StreamStorageError::MissingPrefix | The source omitted a prefix not yet stored in this database. |
StreamStorageError::UninitializedNetworkProgress | Existing progress was not written by ordered admission. |
StreamStorageError::Capacity | Pending work exceeds its row or byte budget. Retry after processing drains it. |
StreamStorageError::HeadChanged | Another processor changed the pending head. Reload state before retrying. |
StreamStorageError::StaleJoinAnchor | Installing this welcome would rewind or replace processed state. |
StreamStorageError::AlreadyActive | Another default consumer holds an unexpired lease. |
StreamStorageError::NotCurrentOwner | The lease expired or a new consumer acquired ownership. |
StreamStorageError::ForeignCursor | The cursor was issued before restore or by another database. |
StreamStorageError::DeliveryExhausted | The persistent local message counter cannot allocate another number. |
StreamStorageError::LocalReadCapacity | The next retained message exceeds the local read byte limit. Not retryable. |
StreamStorageError::InvalidDeliveryPosition | The cursor is ahead of local history or the lease interval is empty. |
xmtp_id
Section titled “xmtp_id”AccountIdError enum
Section titled “AccountIdError enum”crates/xmtp_id/src/associations/signature.rs
| Error Code | Description |
|---|---|
AccountIdError::InvalidChainId | Invalid chain ID. Chain ID is not a valid u64. Not retryable. |
AccountIdError::MissingEip155Prefix | Missing EIP-155 prefix. Chain ID is not prefixed with eip155:. Not retryable. |
AssociationError enum
Section titled “AssociationError enum”crates/xmtp_id/src/associations/association_log.rs
| Error Code | Description |
|---|---|
AssociationError::Generic | Generic association error. Unclassified association error. Not retryable. |
AssociationError::MultipleCreate | Multiple create operations. Duplicate inbox creation detected. Not retryable. |
AssociationError::NotCreated | XID not yet created. Operating on inbox that doesn’t exist yet. Not retryable. |
AssociationError::MemberNotAllowed | Member not allowed. Member kind cannot add the specified kind. Not retryable. |
AssociationError::MissingExistingMember | Missing existing member. Required signer not found or signer identity mismatch. Not retryable. |
AssociationError::LegacySignatureReuse | Legacy signature reuse. Legacy delegated signature used in disallowed context. Not retryable. |
AssociationError::NewMemberIdSignatureMismatch | New member ID signature mismatch. Signer doesn’t match new member identifier. Not retryable. |
AssociationError::WrongInboxId | Wrong Inbox ID. Incorrect inbox_id in association. Not retryable. |
AssociationError::SignatureNotAllowed | Signature not allowed. Signature type not permitted for this role. Not retryable. |
AssociationError::Replay | Replay detected. Replayed identity update detected. Not retryable. |
AssociationError::MissingIdentityUpdate | Missing identity update. Required identity update not provided. Not retryable. |
AssociationError::ChainIdMismatch | Chain ID mismatch. Smart contract wallet chain ID changed. Not retryable. |
AssociationError::InvalidAccountAddress | Invalid account address. Address is not 42-char hex starting with 0x. Not retryable. |
AssociationError::NotIdentifier | Not an identifier. Value is not a valid public identifier. Not retryable. |
DeserializationError enum
Section titled “DeserializationError enum”crates/xmtp_id/src/associations/serialization.rs
| Error Code | Description |
|---|---|
DeserializationError::MissingAction | Missing action. Identity action not present in update. Not retryable. |
DeserializationError::MissingUpdate | Missing update. Identity update not present. Not retryable. |
DeserializationError::MissingMemberIdentifier | Missing member identifier. Member identifier field empty. Not retryable. |
DeserializationError::Signature | Missing signature. Signature field not present. Not retryable. |
DeserializationError::MissingMember | Missing member. Member field not present. Not retryable. |
DeserializationError::Decode | Decode error. Protobuf decoding failed. Not retryable. |
DeserializationError::InvalidAccountId | Invalid account ID. CAIP-10 account ID is malformed. Not retryable. |
DeserializationError::InvalidPasskey | Invalid passkey. Passkey data is malformed. Not retryable. |
DeserializationError::InvalidHash | Invalid hash. Hash must be 32 bytes. Not retryable. |
DeserializationError::Unspecified | Unspecified value. An unrecognized or unsupported value was encountered. Not retryable. |
DeserializationError::Deprecated | Deprecated field. A deprecated field was used. Not retryable. |
DeserializationError::Ed25519 | Ed25519 key error. Failed to create public key from bytes. Not retryable. |
DeserializationError::Bincode | Unable to deserialize. Bincode deserialization failed. Not retryable. |
KeyPackageVerificationError enum
Section titled “KeyPackageVerificationError enum”crates/xmtp_id/src/key_package/verified_key_package_v2.rs
| Error Code | Description |
|---|---|
KeyPackageVerificationError::TlsError | TLS codec error. MLS TLS encoding/decoding failed. Not retryable. |
KeyPackageVerificationError::MlsValidation | MLS validation error. Key package verification failed. Not retryable. |
KeyPackageVerificationError::WrongCredentialType | Wrong credential type. Unexpected MLS credential type. Not retryable. |
SignatureError enum
Section titled “SignatureError enum”crates/xmtp_id/src/associations/signature.rs
| Error Code | Description |
|---|---|
SignatureError::MalformedLegacyKey | Malformed legacy key. Legacy key format is invalid. Not retryable. |
SignatureError::Ed25519Error | Ed25519 signature failed. Ed25519 signature verification failed. Not retryable. |
SignatureError::TryFromSliceError | Slice conversion error. Byte slice conversion failed. Not retryable. |
SignatureError::Invalid | Signature validation failed. Signature did not verify. Not retryable. |
SignatureError::UrlParseError | URL parse error. URL parsing failed. Not retryable. |
SignatureError::DecodeError | Decode error. Protobuf decoding failed. Not retryable. |
SignatureError::Signer | Signer error. Cryptographic signer operation failed. Not retryable. |
SignatureError::InvalidPublicKey | Invalid public key. Public key is not valid. Not retryable. |
SignatureError::InvalidClientData | Invalid client data. Client data is malformed. Not retryable. |
SignatureError::SignerError | Alloy signer error. Ethereum signer failed. Not retryable. |
SignatureError::Signature | Alloy signature error. Ethereum signature parsing failed. Not retryable. |
SignatureRequestError enum
Section titled “SignatureRequestError enum”crates/xmtp_id/src/associations/builder.rs
| Error Code | Description |
|---|---|
SignatureRequestError::UnknownSigner | Unknown signer. Signer not recognized for this request. Not retryable. |
SignatureRequestError::MissingSigner | Missing signer. Required signature was not provided. Not retryable. |
SignatureRequestError::BlockNumber | Unable to get block number. Block number not returned after successful SCW verification. May be retryable. |
SignatureRequestError::ChainNotAccepted | The deployment does not accept this chain. The smart contract wallet signature names a chain outside the list the backend published (CFG-069, CFG-070). Not retryable. |
VerifierError enum
Section titled “VerifierError enum”crates/xmtp_id/src/scw_verifier/mod.rs
| Error Code | Description |
|---|---|
VerifierError::UnexpectedERC6492Result | Unexpected ERC-6492 result. Smart contract wallet signature verification returned unexpected result. Not retryable. |
VerifierError::Provider | Provider error. Ethereum RPC provider error. Retryable. |
VerifierError::Url | URL parse error. Verifier URL is malformed. Not retryable. |
VerifierError::Io | I/O error. I/O operation failed. May be retryable. |
VerifierError::Serde | Serialization error. JSON serialization/deserialization failed. Not retryable. |
VerifierError::MalformedEipUrl | Malformed chain ID. Chain ID string lacks expected eip155: prefix. Not retryable. |
VerifierError::NoVerifier | No verifier. Verifier not configured for the given chain ID. Retryable. |
VerifierError::InvalidHash | Invalid hash. Hash has invalid length or format. Not retryable. |
VerifierError::Other | Other error. Unclassified verifier error. May be retryable. |
xmtp_mls
Section titled “xmtp_mls”BarrierError enum
Section titled “BarrierError enum”crates/xmtp_mls/src/subscriptions/barrier.rs
| Error Code | Description |
|---|---|
BarrierError::Incomplete | Processing did not meet the fixed targets. Pending work remains durable. May be retryable. |
CatchUpError enum
Section titled “CatchUpError enum”crates/xmtp_mls/src/subscriptions/catch_up.rs
| Error Code | Description |
|---|---|
CatchUpError::Incomplete | Fixed targets remain unfinished. Partial committed progress is retained. May be retryable. |
ClientBuilderError enum
Section titled “ClientBuilderError enum”crates/xmtp_mls/src/builder.rs
| Error Code | Description |
|---|---|
ClientBuilderError::MissingParameter | Missing parameter. Required builder parameter not provided. Not retryable. |
ClientBuilderError::ClientError | Client error. Client operation failed during build. May be retryable. |
ClientBuilderError::StorageError | Storage error. Storage initialization failed. Not retryable. |
ClientBuilderError::Identity | Identity error. Identity creation/loading failed. Not retryable. |
ClientBuilderError::WrappedApiError | API error. API client initialization failed. Retryable. |
ClientBuilderError::GroupError | Group error. Group operation failed during build. Not retryable. |
ClientBuilderError::DeviceSync | Device sync error. Device sync setup failed. Not retryable. |
ClientBuilderError::OfflineBuildFailed | Offline build failed. Builder tried to access the network in offline mode. Not retryable. |
ClientError enum
Section titled “ClientError enum”crates/xmtp_mls/src/client.rs
| Error Code | Description |
|---|---|
ClientError::PublishError | Could not publish. Failed to publish messages to the network. May be retryable. |
ClientError::Storage | Storage error. Database operation failed. May be retryable. |
ClientError::Api | API error. Network request to XMTP backend failed. Retryable. |
ClientError::Identity | Identity error. Problem with identity operations. Not retryable. |
ClientError::TlsError | TLS Codec error. Encoding/decoding MLS TLS structures failed. Not retryable. |
ClientError::KeyPackageVerification | Key package verification failed. Invalid key package received from network. Not retryable. |
ClientError::StreamInconsistency | Stream inconsistency. Message stream state became inconsistent. Not retryable. |
ClientError::Association | Association error. Identity association operation failed. Not retryable. |
ClientError::SignatureValidation | Signature validation error. A signature failed verification. Not retryable. |
ClientError::IdentityUpdate | Identity update error. Failed to process identity update. Not retryable. |
ClientError::SignatureRequest | Signature request error. Failed to create/process signature request. Not retryable. |
ClientError::Group | Group error. Group operation failed. May be retryable. |
ClientError::LocalEvent | Local event error. Failed to process local event. Not retryable. |
ClientError::Db | Database connection error. Connection to database failed. Retryable. |
ClientError::Generic | Generic error. Unclassified error. May be retryable. |
ClientError::MlsStore | MLS store error. OpenMLS key store operation failed. Not retryable. |
ClientError::EnrichMessage | Message enrichment error. Failed to enrich message content. Not retryable. |
ClientError::Conversion | Conversion Error Data type failed to convert. Not retryable. |
ClientError::RegistrationNotVisible | Registration not visible. Registration has no publish cursor or is not visible before the timeout. Not retryable. |
ClientError::AlreadyClosed | Client is closed. Operation was attempted on a client that has been shut down via Client::close. Not retryable — build a new client instead. |
ClientError::ConfigurationUnavailable | Server configuration unavailable. The backend did not serve its configuration, or the answer could not be stored. A backend older than spec 006 answers UNIMPLEMENTED; there is no compatibility shim. Retryable exactly when the wrapped failure is: an unreachable backend is worth another attempt, UNIMPLEMENTED is not. |
ClientError::ConfigurationInvalid | Server configuration invalid. The backend published a configuration this client cannot use: a missing or malformed identifier, a minimum version that does not parse, or a chain that is not a CAIP-2 identifier. Not retryable. |
ClientError::BackendMismatch | Backend mismatch. This database is bound to one backend deployment and a different one answered. Not retryable — use a database created for the backend this app now points at. |
ClientError::ClientVersionTooOld | Client version too old. The backend requires a newer libxmtp than this build. Not retryable — ship an updated client. |
ClientError::AuthRequired | Authentication required. The backend requires a credential and none was configured. Not retryable — supply an auth callback or handle before building. |
ClientError::ChainNotAccepted | Chain not accepted. The backend does not verify smart contract wallet signatures on this chain. Not retryable — use a chain the deployment accepts. |
DeviceSyncError enum
Section titled “DeviceSyncError enum”crates/xmtp_mls/src/worker/device_sync/mod.rs
| Error Code | Description |
|---|---|
DeviceSyncError::IO | I/O error. File system or network I/O failed. May be retryable. |
DeviceSyncError::Serde | Serialization error. JSON serialization/deserialization failed. Retryable. |
DeviceSyncError::AesGcm | AES-GCM encryption error. Encryption/decryption of sync payload failed. Retryable. |
DeviceSyncError::Conversion | Type conversion error. Internal type conversion failed. Retryable. |
DeviceSyncError::UTF8 | UTF-8 error. String is not valid UTF-8. Retryable. |
DeviceSyncError::InvalidPayload | Invalid payload. Sync message payload is malformed. Retryable. |
DeviceSyncError::UnspecifiedDeviceSyncKind | Unspecified sync kind. Device sync kind not specified. Not retryable. |
DeviceSyncError::Bincode | Bincode error. Binary serialization failed. Retryable. |
DeviceSyncError::Archive | Archive error. Sync archive operation failed. Retryable. |
DeviceSyncError::Decode | Decode error. Protobuf decoding failed. Retryable. |
DeviceSyncError::MissingSyncGroup | Missing sync group. Sync group not found. Not retryable. |
DeviceSyncError::Sync | Sync summary. Sync completed with errors. May be retryable. |
DeviceSyncError::MlsStore | MLS store error. OpenMLS key store operation failed. Retryable. |
DeviceSyncError::Recv | Receive error. Channel receive failed. Retryable. |
DeviceSyncError::MissingField | Missing field. Required field not present. Retryable. |
EnrichMessageError enum
Section titled “EnrichMessageError enum”crates/xmtp_mls/src/messages/enrichment.rs
| Error Code | Description |
|---|---|
EnrichMessageError::CodecError | Codec decode error. Content type codec failed. Not retryable. |
EnrichMessageError::DecodeError | Decode error. Protobuf decoding failed. Not retryable. |
GroupError enum
Section titled “GroupError enum”crates/xmtp_mls/src/groups/error.rs
| Error Code | Description |
|---|---|
GroupError::UserLimitExceeded | Max user limit exceeded. Attempted to add too many members. Not retryable. |
GroupError::MissingSequenceId | Sequence ID not found. No sequence ID for an inbox after an identity-update refresh — its registration hasn’t propagated yet. Retryable. |
GroupError::AddressNotFound | Addresses not found. Specified addresses have no XMTP identity. Not retryable. |
GroupError::WrappedApi | API error. Network request failed. Retryable. |
GroupError::InvalidGroupMembership | Invalid group membership. Group membership state is invalid. Not retryable. |
GroupError::LeaveCantProcessed | Leave cannot be processed. Group leave validation failed. Not retryable. |
GroupError::Storage | Storage error. Database operation failed. May be retryable. |
GroupError::Intent | Intent error. Failed to process group intent. Not retryable. |
GroupError::CreateMessage | Create message error. MLS message creation failed. Not retryable. |
GroupError::TlsError | TLS codec error. MLS TLS encoding/decoding failed. Not retryable. |
GroupError::UpdateGroupMembership | Update group membership error. Failed to update group membership. May be retryable. |
GroupError::GroupCreate | Group create error. MLS group creation failed. May be retryable. |
GroupError::SelfUpdate | Self update error. MLS self-update operation failed. May be retryable. |
GroupError::WelcomeError | Welcome error. Processing MLS welcome message failed. May be retryable. |
GroupError::InvalidExtension | Invalid extension. MLS extension validation failed. Not retryable. |
GroupError::Signature | Invalid signature. MLS signature verification failed. Not retryable. |
GroupError::Client | Client error. Client operation failed within group. May be retryable. |
GroupError::ReceiveError | Receive error. Processing received group message failed. May be retryable. |
GroupError::AddressValidation | Address validation error. An address/identifier is invalid. Not retryable. |
GroupError::LocalEvent | Local event error. Failed to process local event. Not retryable. |
GroupError::InvalidPublicKeys | Invalid public keys. Keys are not valid Ed25519 public keys. Not retryable. |
GroupError::CommitValidation | Commit validation error. MLS commit validation failed. May be retryable. |
GroupError::Identity | Identity error. Identity operation failed. Not retryable. |
GroupError::ConversionError | Conversion error. Proto conversion failed. Not retryable. |
GroupError::CryptoError | Crypto error. Cryptographic operation failed. Not retryable. |
GroupError::CreateGroupContextExtProposalError | Group context proposal error. Failed to create group context extension proposal. May be retryable. |
GroupError::ProposeAddMember | Propose add member error. Failed to create an add-member proposal. May be retryable. |
GroupError::ProposeRemoveMember | Propose remove member error. Failed to create a remove-member proposal. May be retryable. |
GroupError::Proposal | Proposal error. Generic MLS proposal creation/handling failure. May be retryable. |
GroupError::CommitToPendingProposals | Commit to pending proposals error. Failed to commit pending proposals into an MLS commit. May be retryable. |
GroupError::MergePendingCommit | Merge pending commit error. Failed to merge a pending commit into local state. May be retryable. |
GroupError::ProposalsNotSupported | Proposals not supported. Encountered a proposal when our client does not support proposals. Not retryable. |
GroupError::MinVersionExceedsOwnVersion | Caller asked to set MIN_SUPPORTED_PROTOCOL_VERSION to a value the caller’s own client does not satisfy. Refusing prevents the caller from immediately pausing themselves (and every peer at or below their version) the moment the bump lands. Not retryable. |
GroupError::MinVersionDowngrade | Caller asked to lower MIN_SUPPORTED_PROTOCOL_VERSION below the floor already on the group. Monotonic-only: a downgrade would silently unpause peers between the old and new floors, defeating the gate. Not retryable. |
GroupError::InvalidMinVersion | Caller passed a min_version string that doesn’t parse as semver. Surfaces from the send-side paths (enable_proposals, update_group_min_version) so SDK consumers can match-handle malformed input without parsing string-flattened wrappers. Not retryable. |
GroupError::ComponentSource | Component source error. Failed to encode, decode, or look up a well-known component during the AppDataUpdate path. Not retryable. |
GroupError::AppDataCommit | AppData commit error. Failed to build or stage a commit that bundles an inline AppDataUpdate proposal. Wraps the structured GroupAppDataError from stage_app_data_propose_and_commit so the underlying OpenMLS create/stage failure is preserved instead of being string-flattened. |
GroupError::BootstrapSynthesis | Bootstrap synthesis failure — sender-side couldn’t build the complete set of initial component values for the migration commit. Includes identity-update lookup failures. Conditionally retryable: delegates to the wrapped [super::app_data::migration::BootstrapSynthesisError], which retries only when an inner identity-update API error is itself retryable. Decode/registry-shape failures are deterministic and not retryable. |
GroupError::BootstrapCommit | Bootstrap commit-build failure. Not retryable: every variant of [super::app_data::migration::BootstrapCommitError] is a deterministic OpenMLS commit failure, a TLS codec error, or a caller-side precondition violation. |
GroupError::CredentialError | Credential error. MLS credential validation failed. Not retryable. |
GroupError::LeafNodeError | Leaf node error. MLS leaf node operation failed. Not retryable. |
GroupError::InstallationDiff | Installation diff error. Installation diff computation failed. May be retryable. |
GroupError::NoPSKSupport | No PSK support. Pre-shared keys are not supported. Not retryable. |
GroupError::SqlKeyStore | SQL key store error. OpenMLS key store operation failed. May be retryable. |
GroupError::SyncFailedToWait | Sync failed to wait. Waiting for intent sync failed. Retryable. |
GroupError::PublishedButUnconfirmed | The exact published attempt remains pending. A later call can confirm it. Retryable. |
GroupError::MissingPendingCommit | Missing pending commit. Expected pending commit not found. Not retryable. |
GroupError::ProcessIntent | Process intent error. Failed to process group intent. May be retryable. |
GroupError::LockUnavailable | Failed to load lock. Concurrency lock acquisition failed. Retryable. |
GroupError::TooManyCharacters | Exceeded max characters. Field value exceeds character limit. Not retryable. |
GroupError::AppDataSuperseded | A guarded metadata update was abandoned because another member changed the field first. Not retryable as-is: the value was derived from state that no longer exists. Re-derive it from actual and queue a new update. Distinct from a sync failure — nothing went wrong, the write is just stale. |
GroupError::GroupPausedUntilUpdate | Group paused until update. Group is paused until a newer version is available. Not retryable. |
GroupError::GroupInactive | Group is inactive. Operation on an inactive group. Not retryable. |
GroupError::Sync | Sync summary. Sync operation completed with errors. May be retryable. |
GroupError::Db | Database connection error. Database connection failed. Retryable. |
GroupError::MlsStore | MLS store error. OpenMLS key store failed. Not retryable. |
GroupError::MetadataPermissionsError | Metadata permissions error. Metadata permission check failed. Not retryable. |
GroupError::FailedToVerifyInstallations | Failed to verify installations. Installation verification failed. Not retryable. |
GroupError::NoWelcomesToSend | No welcomes to send. No welcome messages to send to new members. Not retryable. |
GroupError::CodecError | Codec error. Content type codec failed. Retryable. |
GroupError::WrapWelcome | Wrap welcome error. Failed to wrap welcome message. Not retryable. |
GroupError::UnwrapWelcome | Unwrap welcome error. Failed to unwrap welcome message. Not retryable. |
GroupError::WelcomeDataNotFound | Welcome data not found. Welcome data missing from topic. Not retryable. |
GroupError::WelcomeGroupPrefixPending | The old group must process its ordered prefix before this Welcome can install. Retryable. |
GroupError::InvalidWelcomeMetadata | The Welcome has missing, malformed, or out-of-range join metadata. Not retryable. |
GroupError::UnsupportedWelcomeVersion | The Welcome needs a newer client. Keep it blocked until upgrade. Retryable. |
GroupError::UninitializedResult | Result not initialized. Expected result was not initialized. Not retryable. |
GroupError::Diesel | Diesel ORM error. Raw database query failed. May be retryable. |
GroupError::UninitializedField | Uninitialized field. Builder field not initialized. Not retryable. |
GroupError::DeleteMessage | Delete message error. Failed to delete message. Not retryable. |
GroupError::DeviceSync | Device sync error. Device sync operation failed. May be retryable. |
GroupMutablePermissionsError enum
Section titled “GroupMutablePermissionsError enum”crates/xmtp_mls/src/groups/group_permissions.rs
Errors that can occur when working with GroupMutablePermissions.
| Error Code | Description |
|---|---|
GroupMutablePermissionsError::Serialization | Serialization error. Failed to encode permissions protobuf. Not retryable. |
GroupMutablePermissionsError::Deserialization | Deserialization error. Failed to decode permissions protobuf. Not retryable. |
GroupMutablePermissionsError::Policy | Policy error. Permission policy validation failed. Not retryable. |
GroupMutablePermissionsError::InvalidConversationType | Invalid conversation type. Wrong conversation type for this operation. Not retryable. |
GroupMutablePermissionsError::MissingPolicies | Missing policies. Required permission policies not present. Not retryable. |
GroupMutablePermissionsError::MissingExtension | Missing extension. Required MLS extension not found. Not retryable. |
GroupMutablePermissionsError::InvalidPermissionPolicyOption | Invalid permission policy option. Invalid permission policy configuration. Not retryable. |
IdentityError enum
Section titled “IdentityError enum”crates/xmtp_mls/src/identity.rs
| Error Code | Description |
|---|---|
IdentityError::CredentialSerialization | Credential serialization error. Failed to encode MLS credential. Not retryable. |
IdentityError::Decode | Decode error. Protobuf decoding failed. Not retryable. |
IdentityError::InstallationIdNotFound | Installation not found. Installation ID not found in network association state. Not retryable. |
IdentityError::BasicCredential | Basic credential error. MLS basic credential validation failed. Not retryable. |
IdentityError::LegacyKeyReuse | Legacy key re-use. Attempted to reuse a legacy key. Not retryable. |
IdentityError::UninitializedIdentity | Uninitialized identity. Identity not yet initialized. Not retryable. |
IdentityError::InstallationKey | Installation key error. Problem with installation key. Not retryable. |
IdentityError::MalformedLegacyKey | Malformed legacy key. Legacy key format is invalid. Not retryable. |
IdentityError::LegacySignature | Legacy signature error. Legacy signature is invalid. Not retryable. |
IdentityError::Crypto | Crypto error. Cryptographic operation failed. Not retryable. |
IdentityError::LegacyKeyMismatch | Legacy key mismatch. Legacy key does not match address. Not retryable. |
IdentityError::OpenMls | OpenMLS error. OpenMLS library error. Not retryable. |
IdentityError::KeyPackageGenerationError | Key package generation error. Failed to generate MLS key package. Not retryable. |
IdentityError::InboxIdMismatch | Inbox ID mismatch. Associated InboxID does not match stored value. Not retryable. |
IdentityError::NoAssociatedInboxId | No associated Inbox ID. Address has no associated InboxID. Not retryable. |
IdentityError::RequiredIdentityNotFound | Required identity not found. Identity was not found in cache. Not retryable. |
IdentityError::NewIdentity | New identity creation error. Error creating a new identity. Not retryable. |
IdentityError::Signer | Signer error. Cryptographic signer failed. Not retryable. |
IdentityError::IdentityUpdate | Identity publication failed. Retryability depends on the cause. |
IdentityError::TooManyInstallations | Too many installations. InboxID has reached max installation count. Not retryable. |
IdentityError::InvalidExtension | Invalid extension error. MLS extension validation failed. Not retryable. |
IdentityError::MissingPostQuantumPublicKey | Missing PQ public key. Post-quantum public key not found. Not retryable. |
IdentityError::Bincode | Bincode serialization error. Binary serialization failed. Not retryable. |
IdentityError::UninitializedField | Uninitialized field. Builder field not initialized. Not retryable. |
LocalDeliveryError enum
Section titled “LocalDeliveryError enum”crates/xmtp_mls/src/subscriptions/local_delivery/types.rs
| Error Code | Description |
|---|---|
LocalDeliveryError::AcknowledgementRejected | The callback failed or its token was dropped before acknowledgement. Not retryable. |
LocalDeliveryError::AcknowledgementFailed | A previous acknowledgement write failed. Reopen to retry delivery. Not retryable. |
LocalDeliveryError::SelectionChanged | Scope, filters, or retained content changed before dispatch. Reselect without acknowledgement. |
LocalDeliveryError::InvalidConfiguration | The batch or timing settings cannot maintain a valid consumer lease. Not retryable. |
LocalDeliveryError::Closed | This reader has been closed. Not retryable. |
NotificationError enum
Section titled “NotificationError enum”crates/xmtp_mls/src/client/notifications.rs
Errors use fixed messages and never include notification credentials.
| Error Code | Description |
|---|---|
NotificationError::TaskRunnerDisabled | The task runner is disabled. Not retryable. |
NotificationError::PermissionDenied | The recipient credential was rejected. Not retryable. |
NotificationError::InvalidArgument | The delivery configuration is invalid. Not retryable. |
NotificationError::OutOfRange | A notification value is outside the allowed range. Not retryable. |
NotificationError::Unimplemented | The backend does not support notifications. Not retryable. |
NotificationError::ChannelNotConfigured | The delivery channel is not configured. Not retryable. |
NotificationError::ResourceExhausted | The recipient topic limit was reached. Retry after the desired set changes. |
NotificationError::RequestTimeout | The notification request exceeded its time limit. Retryable. |
NotificationError::NotFound | The recipient must register again. Retryable. |
SubscribeError enum
Section titled “SubscribeError enum”crates/xmtp_mls/src/subscriptions/mod.rs
| Error Code | Description |
|---|---|
SubscribeError::Transport | The shared native transport failed. May be retryable. |
SubscribeError::Group | Group error. Group operation failed during subscription. May be retryable. |
SubscribeError::NotFound | Not found. Subscribed resource not found. Retryable. |
SubscribeError::GroupMessageNotFound | Group message not found. Expected message missing from database. Retryable. |
SubscribeError::ReceiveGroup | Receive group error. Processing streamed group message failed. May be retryable. |
SubscribeError::Storage | Storage error. Database operation failed. May be retryable. |
SubscribeError::Decode | Decode error. Protobuf decoding failed. Not retryable. |
SubscribeError::ApiClient | API client error. Network request failed. Retryable. |
SubscribeError::BoxError | Boxed error. Wrapped dynamic error. May be retryable. |
SubscribeError::Db | Database connection error. Database connection failed. Retryable. |
SubscribeError::Conversion | Conversion error. Proto conversion failed. Not retryable. |
SubscribeError::Envelope | Envelope error. Invalid backend envelope. Not retryable. |
SubscribeError::Enriched | Enriched Message Error. |
SubscribeError::StreamStale | Stream liveness watchdog tripped. No activity arrived within the idle timeout, so the stream was terminated to force a reconnect (resuming from the persisted cursor). Retryable. |
xmtp_mls_common
Section titled “xmtp_mls_common”GroupMetadataError enum
Section titled “GroupMetadataError enum”crates/xmtp_mls_common/src/group_metadata.rs
| Error Code | Description |
|---|---|
GroupMetadataError::Serialization | Serialization error. Failed to encode metadata protobuf. Not retryable. |
GroupMetadataError::Deserialization | Deserialization error. Failed to decode metadata protobuf. Not retryable. |
GroupMetadataError::InvalidConversationType | Invalid conversation type. Protobuf conversation type not recognized. Not retryable. |
GroupMetadataError::MissingExtension | Missing extension. Immutable metadata MLS extension not found. Not retryable. |
GroupMetadataError::InvalidDmMembers | Invalid DM members. DM member data is invalid. Not retryable. |
GroupMetadataError::MissingDmMember | Missing DM member. A DM member field is not set. Not retryable. |
xmtp_proto
Section titled “xmtp_proto”ApiClientError enum
Section titled “ApiClientError enum”crates/xmtp_proto/src/traits/error.rs
| Error Code | Description |
|---|---|
ApiClientError::ClientWithEndpoint | The client encountered an error. |
ApiClientError::Client | The transport failed. Retryability follows the source. |
ApiClientError::Http | The HTTP request is invalid. Not retryable. |
ApiClientError::Body | The request body is invalid. Not retryable. |
ApiClientError::DecodeError | The response cannot be decoded. Not retryable. |
ApiClientError::Conversion | A protocol conversion failed. Not retryable. |
ApiClientError::ProtoError | A protocol operation failed. Not retryable. |
ApiClientError::InvalidUri | The URI is invalid. Not retryable. |
ApiClientError::Expired | The request expired. Retryable. |
ApiClientError::Other | A client operation failed. Retryability follows the source. |
ApiClientError::OtherUnretryable | A client operation failed. Not retryable. |
ApiClientError::WritesDisabled | Writes are disabled. Not retryable. |
AuthError enum
Section titled “AuthError enum”crates/xmtp_proto/src/traits/error.rs
Authentication failures with no credential or callback error text.
| Error Code | Description |
|---|---|
AuthError::CredentialRejected | The backend rejected the credential. Retryable if a callback can run. |
AuthError::CallbackFailed | The callback failed. Retryable if a callback can run. |
AuthError::Exhausted | Authentication is locked until the cool-down ends. Not retryable. |
AuthError::MissingCredential | No credential was set on the handle. Not retryable. |
ConversionError enum
Section titled “ConversionError enum”crates/xmtp_proto/src/error.rs
General Error types for use when converting/deserializing From/To Protos Loosely Modeled after serdes error type. This general error type avoid circular hard-dependencies on crates further up the tree (xmtp_id/xmtp_mls) if they had defined the error themselves.
| Error Code | Description |
|---|---|
ConversionError::Missing | Missing field. Required field missing during proto conversion. Not retryable. |
ConversionError::Unspecified | Unspecified field. Protobuf field is unspecified. Not retryable. |
ConversionError::Deprecated | Deprecated field. A deprecated protobuf field was used. Not retryable. |
ConversionError::InvalidLength | Invalid length. Data has wrong length for conversion. Not retryable. |
ConversionError::InvalidValue | Invalid value. Data has unexpected value. Not retryable. |
ConversionError::Decode | Decode error. Protobuf decoding failed. Not retryable. |
ConversionError::Encode | Encode error. Protobuf encoding failed. Not retryable. |
ConversionError::UnknownEnumValue | Unknown enum value. Protobuf enum has unrecognized value. Not retryable. |
ConversionError::EdSignature | Ed25519 signature error. Ed25519 signature bytes invalid. Not retryable. |
ConversionError::InvalidPublicKey | Invalid public key. Public key validation failed. Not retryable. |
ConversionError::InvalidVersion | Invalid version. Protocol version not supported. Not retryable. |
ConversionError::OpenMls | OpenMLS error. OpenMLS library error. Not retryable. |
ConversionError::Protocol | Protocol message error. MLS protocol message error. Not retryable. |
ConversionError::Builder | Builder error. Builder field not initialized. Not retryable. |
ConversionError::Slice | Slice error. Byte slice conversion failed. Not retryable. |
ProtoError enum
Section titled “ProtoError enum”crates/xmtp_proto/src/error.rs
Error resulting from proto conversions/mutations
| Error Code | Description |
|---|---|
ProtoError::Hex | Hex error. Hex encoding/decoding failed. Not retryable. |
ProtoError::Decode | Decode error. Protobuf decoding failed. Not retryable. |
ProtoError::Encode | Encode error. Protobuf encoding failed. Not retryable. |
ProtoError::OpenMls | OpenMLS error. OpenMLS library error. Not retryable. |
ProtoError::MlsProtocolMessage | MLS protocol message error. MLS framing error. Not retryable. |
ProtoError::KeyPackage | Key package error. Key package verification failed. Not retryable. |
ProtoError::NotFound | Not found. Proto resource not found. Not retryable. |