Docs / Reference

Error codes

Ghoti answers a failed command with a short code instead of a message, which keeps every response small.

Source of truth

The authoritative list is internal/errs/README.md. The server embeds that file at compile time and reads its codes from it, so the code and the list can't drift apart. This page is a copy of it. If they ever disagree, the file in the repository wins.

Format#

An error is e, three characters for the slot, and three digits for the code. For slot 135 and error 006:

< e135006

Errors that aren't about a specific slot, such as a parse error, use xxx as the slot:

< exxx001

An error can carry an argument after the code. In a cluster, a follower answers with 000 followed by the leader's node ID, so the client knows which node to contact:

< exxx000node1

Summary#

CodeNameCloses connectionHTTP status
000NOT_LEADERNo503
001PARSE_ERRORNo400
002WRONG_USERYesNot applicable
003WRONG_PASSYesNot applicable
004WRONG_LOGINYesNot applicable (401 for bad Basic Auth)
005MISSING_SLOTNo404
006WRITE_PERMISSIONNo403
007WRITE_FAILEDNo400
008READ_PERMISSIONNo403
009WRONG_FORMATReserved, not returnedNot applicable
010UNSUPPORTED_COMMANDNoNot applicable

000: NOT_LEADER#

This node is not the leader. Send the command to the leader node.

In cluster mode only the leader can be used to read and write. A follower answers every command with this error, followed by the name of the leader node:

< exxx000nodeA

Here nodeA is the node to contact. How the client maps that name to an address depends on how the cluster and the client were set up. See Routing traffic to the leader.

001: PARSE_ERROR#

The message couldn't be parsed: it doesn't follow the protocol. The cases that produce it are:

This error is never tied to a slot, so it is always exxx001.

002: WRONG_USER#

The username is too short or contains invalid characters: it is shorter than 4 bytes, or doesn't match ^[a-zA-Z][a-zA-Z0-9_]*$ (a letter, then letters, numbers or underscores).

The connection is closed after this error.

003: WRONG_PASS#

The password is too short: it is shorter than 4 bytes, or the username set before it was invalid.

The connection is closed after this error.

004: WRONG_LOGIN#

No configured user matches the username and password sent.

The connection is closed after this error.

005: MISSING_SLOT#

The slot addressed by the command is not configured. The slot number is valid and in range, but no slot with that number is defined in the configuration. Unlike the login errors, this response carries the requested slot number rather than xxx, for example e999005.

A slot whose definition is invalid is ignored at startup, so it also answers 005. See Slot reference.

006: WRITE_PERMISSION#

The logged-in user doesn't have permission to write this slot. If no user is logged in, the slot doesn't allow anonymous writes.

Token bucket and leaky bucket slots can't be written at all, so every write to them gets this error.

007: WRITE_FAILED#

The write was allowed, but the slot rejected it. Currently this happens when:

This is not a permission error: 006 means the user may not write the slot at all, while 007 means the write was allowed but the slot rejected it.

008: READ_PERMISSION#

The logged-in user doesn't have permission to read this slot. If no user is logged in, the slot doesn't allow anonymous reads. s and d need read permission too.

009: WRONG_FORMAT#

The message doesn't have the right format.

This code is reserved and not returned by the server: malformed messages are reported as 001. It is kept so the code stays stable if the two cases are ever separated.

010: UNSUPPORTED_COMMAND#

The command is not supported by this slot. s (subscribe) and d (deregister) only work on slots that manage a group of clients, such as multicast slots. Sending them to any other kind of slot returns this error.

Found something out of date? Open an issue or edit this page.