ERROR_CODES.md
This is the list of operational codes that can help you understand your deployment and your usage.
| Code | Description |
|---|---|
| TopicNameRequired | You are trying to use Realtime without a topic name set |
| InvalidJoinPayload | The payload provided to Realtime on connect is invalid |
| RealtimeDisabledForConfiguration | The configuration provided to Realtime on connect will not be able to provide you any Postgres Changes |
| TenantNotFound | The tenant you are trying to connect to does not exist |
| MissingAPIKey | No API key was provided in the x-api-key header or apikey query parameter |
| ErrorConnectingToWebsocket | Error when trying to connect to the WebSocket server |
| UnableToDeleteTenant | Error when trying to delete a tenant |
| UnableToSetPolicies | Error when setting up Authorization Policies |
| UnableCheckoutConnection | Error when trying to checkout a connection from the tenant pool |
| UnableToSubscribeToPostgres | Error when trying to subscribe to Postgres changes |
| ReconnectSubscribeToPostgres | Postgres changes still waiting to be subscribed |
| ChannelRateLimitReached | The number of channels you can create has reached its limit |
| ConnectionRateLimitReached | The number of connected clients has reached its limit |
| ClientJoinRateLimitReached | The rate of joins per second from your clients has reached the channel limits |
| DatabaseConnectionRateLimitReached | The rate of attempts to connect to tenants database has reached the limit |
| MessagePerSecondRateLimitReached | The rate of messages per second from your clients has reached the channel limits |
| RealtimeDisabledForTenant | Realtime has been disabled for the tenant |
| UnableToConnectToTenantDatabase | Realtime was not able to connect to the tenant's database |
| DatabaseLackOfConnections | Realtime was not able to connect to the tenant's database due to not having enough available connections |
| DatabaseIpVersionIsIpv4 | The tenant database host resolved to an IPv4 address while an IPv6 connection was expected |
| RealtimeNodeDisconnected | Realtime is a distributed application and this means that one the system is unable to communicate with one of the distributed nodes |
| MigrationsFailedToRun | Error when running the migrations against the Tenant database that are required by Realtime |
| StartReplicationFailed | Error when starting the replication and listening of errors for database broadcasting |
| ReplicationConnectionTimeout | Replication connection timed out during initialization |
| ReplicationConnectionDown | The replication connection was terminated and a recovery window has been opened |
| ReplicationConnectionRecoveryFailed | The database check failed while trying to recover the replication connection |
| ReplicationConnectionWatchdogTimeout | The replication connection stopped responding and was flagged by its watchdog |
| ReplicationMaxWalSendersReached | Maximum number of WAL senders reached in tenant database, check how to increase this value in this link |
| PartitionCreationFailed | Error when creating partitions for realtime.messages |
| MissingPartition | Realtime was unable to find the expected messages partition |
| ErrorStartingPostgresCDC | Error when starting the Postgres CDC extension which is used for Postgres Changes |
| ReplicationSlotBeingUsed | The replication slot is being used by another transaction |
| PoolingReplicationPreparationError | Error when preparing the replication slot |
| PoolingReplicationError | Error when pooling the replication slot |
| CheckOidsError | Error when fetching the publication tables (OIDs) during the periodic check; the existing OIDs, replication slot and subscribers are left untouched |
| SubscriptionCleanupFailed | Error when trying to clean up all subscriptions on subscription manager initialization or OID change |
| SubscriptionDeletionFailed | Error when trying to delete a subscription for postgres changes |
| ReplicationPollerConnectionFailed | Error when the replication poller process fails to connect to the database on startup |
| ReplicationPollerMaxRetriesReached | The replication poller gave up after the maximum number of consecutive retries and stopped the tenant's Postgres Changes workers |
| DropReplicationSlotFailed | Error when dropping the replication slot after the publication became empty; the poller stops so the temporary slot is released with the connection |
| SubscriptionManagerConnectionFailed | Error when the subscription manager process fails to connect to the database on startup |
| PgStatActivityQueryFailed | Error when querying pg_stat_activity to diagnose a replication slot conflict |
| RateCounterError | Error when retrieving the subscription rate counter, falling back to blocking new subscriptions |
| UnableToCheckProcessesOnRemoteNode | Error when trying to check the processes on a remote node |
| UnhandledProcessMessage | Unhandled message received by a Realtime process |
| UnableToTrackPresence | Error when handling track presence for this socket |
| UnknownPresenceEvent | Presence event type not recognized by service |
| IncreaseConnectionPool | The number of connections you have set for Realtime are not enough to handle your current use case |
| IncreaseSubscriptionConnectionPool | The subscription connection pool hit too many database timeouts and should be increased |
| RlsPolicyError | Error on RLS policy used for authorization |
| UnableToConnectToProject | Unable to connect to Project database |
| JwtSignatureError | JWT signature was not able to be validated |
| MalformedJWT | Token received does not comply with the JWT format |
| Unauthorized | Unauthorized access to Realtime channel |
| RealtimeRestarting | Realtime is currently restarting |
| InvalidPresencePayload | Payload from track event sent to Presence isn't a map |
| UnprocessableEntity | Received a HTTP request with a body that was not able to be processed by the endpoint |
| InitializingProjectConnection | Connection against Tenant database is still starting |
| TimeoutOnRpcCall | RPC request within the Realtime server has timed out. |
| ErrorOnRpcCall | Error when calling another realtime node |
| RpcError | Error returned when calling another realtime node over RPC |
| ErrorExecutingTransaction | Error executing a database transaction in tenant database |
| SynInitializationError | Our framework to synchronize processes has failed to properly startup a connection to the database |
| JanitorFailedToDeleteOldMessages | Scheduled task for realtime.message cleanup was unable to run |
| UnableToEncodeJson | An error were we are not handling correctly the response to be sent to the end user |
| UnableToBroadcastChanges | Error when trying to broadcast database changes to subscribers |
| WarnSendingBroadcastMessage | Warning when realtime.send or realtime.send_binary cannot insert the message. See the troubleshooting guide. |
| UnexpectedMessageReceived | An unexpected message was received by the replication connection process |
| ErrorRunningQuery | Error when running a query against the tenant database |
| QueryCanceled | A database query was canceled, usually due to a statement timeout |
| UnknownError | An unhandled error occurred |
| UnknownErrorOnController | An error we are not handling correctly was triggered on a controller |
| UnknownErrorOnChannel | An error we are not handling correctly was triggered on a channel |
| UnknownErrorOnCounter | An error we are not handling correctly was triggered while reading a rate counter |
| MusterJoinError | Error or timeout while waiting for the channel's Muster membership to land during join |
| PresenceRateLimitReached | Limit of presence events reached |
| ClientPresenceRateLimitReached | Limit of presence events reached on socket |
| UnableToReplayMessages | An error while replaying messages |
| JwtSignerError | Failed to generate a JWT signer — check your JWT secret or JWKS configuration |
| MalformedWebSocketMessage | Received a WebSocket message that is empty, invalid JSON, or missing required fields (ref, topic, or event). The connection is kept alive but the message is dropped |
| UnknownErrorOnWebSocketMessage | An unexpected error occurred while processing an incoming WebSocket message. The connection is kept alive but the message is dropped |
| ReplicationSlotLagTooHigh | The replication slot WAL lag has exceeded 50% of max_slot_wal_keep_size. The replication connection is shut down and will be restarted to prevent the slot from being invalidated by PostgreSQL |
| ReplicationSlotLagCheckSkipped | The periodic replication slot lag check could not be completed, typically because the tenant database connection was unavailable. The check is skipped and retried on the next watchdog interval |
| HttpServerError | Phoenix converted an unhandled exception into a 5xx HTTP response. The log includes the underlying error and status to explain a server error that request metrics alone would not surface |
| HttpClientError | Phoenix converted an exception into a 4xx HTTP response (for example a request to an unknown route). The log includes the underlying error and status |
| JoinsRateLimitReached | The rate of joins per second from your clients has reached the limit and the connection was refused |
| InvalidJWTToken | The JWT provided on connect is expired or is missing required claims (role and exp) |
| PrivateOnly | The connection was rejected because this project only allows private channels |
| UnableToHandleBroadcast | Error when handling a broadcast message |
| UnableToHandlePresence | Error when handling a presence message on a channel |
| ChannelShutdown | The channel was shut down and an error system message was pushed to the client |
| ReplicationRecoveryWindowExceeded | The replication connection recovery window was exceeded and the connection was terminated |
| MigrationCountMismatch | The cached migrations_ran count did not match the tenant database and is being reconciled |
| MigrationCountMismatchReconcileFailed | Failed to reconcile the migrations_ran count mismatch between the cache and the tenant database |
| MetricsPusherTimeout | A metrics push task did not finish within its one minute window and was killed |
| MetricsPusherTaskExited | A metrics push task exited unexpectedly before completing |
| MetricsPusherFailed | Realtime failed to push metrics to the configured endpoint |
| MetricsPusherException | An exception was raised while pushing metrics to the configured endpoint |