Starting and claiming

The server checks its settings, its socket and its data before it opens a port. A refusal is a line in its log, and the server exits.

The server cannot start; fix these settingsCopy anchor link

A setting has a value the server doesn't accept, such as a number out of range. The server checks every setting before it opens the database, and names each one it refused:

The server cannot start; fix these settings:
  RATE_LIMIT_REQUESTS must be a whole number, 1 or more (got "0")

Correct each value it names. Settings lists the values each setting takes.

MARFA_AUTH_SECRET must be set in productionCopy anchor link

With NODE_ENV=production, the server needs API_KEY_SALT, MARFA_AUTH_SECRET and MARFA_AUTH_BASE_URL. It refuses a secret that is missing, short or a placeholder. Outside production it fills in what's missing, but still refuses a MARFA_AUTH_SECRET under 32 characters.

Generate each secret with openssl rand -hex 32, and set MARFA_AUTH_BASE_URL to the address clients use. Deploy shows a complete production setup.

MARFA_CONTROL_SOCKET must be a normalized absolute Unix socket pathCopy anchor link

The full message ends of at most 103 bytes. The server opens a private socket at control/marfa.sock beside the database, and a database deep in the file system makes that path longer than a Unix socket allows.

Keep the data in a shorter directory, or set MARFA_CONTROL_SOCKET to a shorter path. The socket's directory must belong to the account that runs the server, and no one else may read it.

Control path is a symbolic link or not a directoryCopy anchor link

The path to the socket's directory passes through a symbolic link. On macOS, /tmp is one: it points to /private/tmp.

Give the server a path with no links in it, such as /private/tmp/marfa/marfa.db in place of /tmp/marfa/marfa.db. In a shell, pwd -P prints the current directory with its links resolved.

listen EADDRINUSE: address already in useCopy anchor link

Another process listens on the server's port, often an earlier Marfa server that is still running.

Stop the other process, or set PORT to a free port.

I lost the setup codeCopy anchor link

An unclaimed instance prints its setup code when it starts, as Claim this Marfa at /setup with setup code: …. On the instance's own machine, you don't need the code: claim through the private socket, as the Quickstart does.

marfa --socket "$(pwd -P)/data/control/marfa.sock" setup claim --email you@example.com

For a new code, restart the server or run marfa --socket <path> setup code. Either way, the earlier code stops working.

409 owner_existsCopy anchor link

The instance already has an owner, and an instance is claimed only once.

If you are the owner and have lost the password, recover the owner's password from the instance's own machine.

Covered in their guidesCopy anchor link

These refusals belong to one task, and its guide explains them.