Skip to main content
Each heading is a message the gateway or the dashboard shows. The gateway logs to the terminal that runs it, or to docker logs. An error at start is its last line before it exits.

The gateway does not connect

The setup step keeps Waiting for the gateway to connect. If midplane setup stopped, its last line says why; otherwise read the gateway’s last log line.

That is not a Midplane enrollment token

The command holds the placeholder or part of a token (in a config you wrote, secrets/enrollment-token does). Create a token and run the step’s command again.

This enrollment token is unknown, used, revoked or expired

A token works once, within a day, on the Midplane Cloud that made it. Create a new one and run the new command.

A gateway at this URL is already enrolled

Each URL belongs to one gateway. Revoke the old one on its project’s Gateways page, or use another URL. On your computer, each setup makes a new URL.

The cloud may have enrolled this gateway

Setup lost Midplane Cloud’s answer while joining, and removed the files it wrote. If the Gateways page lists the gateway, revoke it. Then create a new token and run setup again. Set up from environment variables, put the new token in the env file, then remove the container and run it again.

No config

no config: mount one at /etc/midplane/midplane.yaml, or set MIDPLANE_ENROLLMENT_TOKEN from your project's setup page: the image found no config to serve and no token to set one up with. Mount your config, start it with the volume it was set up on, or give it the variables of a setup from environment variables.

A setup variable is not set

MIDPLANE_CLOUD_URL is not set, or another variable: setup from environment variables needs it. Add it to the env file or the platform’s secrets. Docker reads an env file only when it creates the container: remove the container and run it again. Nothing was written, and the token is unused.

Already set up

The folder, or in Docker the volume, holds a gateway already. Start it instead: on your computer, npx -y midplane@latest gateway --config <folder>/midplane.yaml; in Docker, the step’s docker run -d command. On your computer each run of setup makes a new folder; in Docker, a new token gives the commands a new volume.

The folder is not empty

/var/lib/midplane isn't empty, naming the folder setup writes to. Setup writes only to a folder that doesn’t exist yet or is empty (a disk’s own lost+found counts as empty), and this one holds files but no midplane.yaml. In Docker, use a new volume: a new token gives the commands one. On your computer, leave out --dir, and setup makes a new folder.

The port is taken

Another program, or another gateway, listens on it. On your computer, setup takes the first free port from 7433 to 7442 unless the command names one with --port: stop the other program, or change the port. In Docker, docker run says the port is already allocated: change Port on the page, which changes -p in the second command.

Cannot read the certificate

can't read /etc/midplane/tls/tls.crt (ENOENT): put the certificate and its key in /etc/midplane/tls on the server, as tls.crt and tls.key. With EACCES, the image’s user (uid 1000) can’t read them: sudo chown 1000 /etc/midplane/tls/tls.key. A file that isn’t PEM is refused too.

The certificate is for another name

the certificate in /etc/midplane/tls/tls.crt is for gw.old.example.com, not gw.example.com: it doesn’t cover the URL’s host. Use one issued for that name, or enter the URL it was issued for.

The certificate expired or is not valid yet

the certificate in /etc/midplane/tls/tls.crt expired on …, or isn't valid until …. Renew it, and check the server’s clock.

The key is not the key of the certificate

/etc/midplane/tls/tls.key isn't the key of the certificate in /etc/midplane/tls/tls.crt. Put the certificate’s own key in tls.key, as PEM and without a passphrase.

The DNS for the URL does not point at this server

the DNS for gw.example.com doesn't point at this server, from setup or as the gateway’s last log line, with an automatic certificate (0.23.0+, as are the headings down to “An automatic certificate needs a host name”). Let’s Encrypt found no address for the host, or fetched its challenge from a server that isn’t this gateway: what it said follows (acme_detail in the log). Point the host’s A record, and AAAA if it has one, at this server (dig +short gw.example.com prints the address), and check that no web server on it takes port 80 first. Then run setup again: the token is unused.

Port 80 is not reachable from the internet

port 80 on gw.example.com isn't reachable from the internet: open it, forwarded to port 7480 here. Let’s Encrypt couldn’t connect to the host on port 80. Open it in the server’s firewall and in your cloud’s network rules or security group; in Docker, both commands map it with -p 80:7480. Without Docker, forward port 80 to 7480, or set tls.acme.http_port: 80 where the gateway may bind it. A server that port 80 can’t reach takes your own certificate.

Certificates for this host are rate limited

Let's Encrypt is rate limiting certificates for gw.example.com: try again later. Let’s Encrypt issues at most five certificates for the same host a week, and allows five failed checks an hour; what it said follows, with when to try again. A setup that stops after getting the certificate spends one, so while you try things out, add (0.23.0+) --acme-directory https://acme-staging-v02.api.letsencrypt.org/directory to setup: its certificates are for tests, and agents don’t trust them.

The CAA records forbid the certificate authority

the CAA records for gw.example.com forbid Let's Encrypt. The domain’s CAA records name the certificate authorities that may issue for it, and Let’s Encrypt isn’t one. Add 0 issue "letsencrypt.org" to them, or use your own certificate.

The certificate authority refused a certificate

Let's Encrypt refused a certificate for gw.example.com, for another reason than the ones above: what it said follows. Fix that, or use your own certificate.

The challenge port is taken

port 7480 is taken: another program, such as a second gateway with an automatic certificate on this host, listens where the challenge is answered. Stop it, or give this gateway another port with tls.acme.http_port and forward port 80 there.

An automatic certificate needs a host name

Let’s Encrypt certifies names, not IP addresses. Give the server a DNS name and use it in the URL, or choose My own under Certificate.

Inside the container, localhost is the container

Setup in Docker connects to each database from inside its container, so localhost and 127.0.0.1 in a connection string are the container itself. Use the database’s host as the server’s network knows it. If the database runs on the same server, the container reaches the server at Docker’s bridge address, by default 172.17.0.1 on Linux (ip addr show docker0 shows it), so use that as the host. Postgres must listen there and admit the container: set listen_addresses = '*', since Postgres can start before Docker adds that address, keep port 5432 closed to the outside in the server’s firewall, and add a pg_hba.conf line for the bridge’s network, by default 172.17.0.0/16. A Postgres in another container publishes its port there: -p 172.17.0.1:5432:5432. On Docker Desktop, use host.docker.internal.

A gateway URL starts with https

http:// URLs only work on your computer (localhost, 127.0.0.1, *.localhost). Use https:// for anything else.

Cannot reach Midplane Cloud

The gateway couldn’t open an HTTPS connection to link.cloud_url: check DNS, firewalls and proxies from its host.

The answer is signed with a key the token does not pin

Something between the gateway and Midplane Cloud intercepts TLS. Let the gateway reach the cloud without TLS inspection. Behind the relay, setup (0.26.1+) checks where the relay is first, and stops before it writes anything, with the token still unused: signed where its relay is with a key the enrollment token doesn't pin, or didn't sign where its relay is for this setup. Check, too, that the token comes from the Midplane Cloud the URL names (MIDPLANE_CLOUD_URL, or --cloud).

This gateway enrolled with another cloud

link.cloud_url changed after enrollment. Put it back, or remove identity.json and enroll with a new token.

Cannot read a secret

databases.shop.dsn: cannot read …: a file the config names is missing or unreadable. In Docker with a config you wrote, let the image’s user read the secrets: sudo chown -R 1000:1000 secrets.

An environment variable the config names is not set

databases.shop.dsn: environment variable SHOP_DSN is not set, or the same for mask_salt or link.enrollment_token: the config takes the value from the environment (dsn: { env: SHOP_DSN }), and the gateway’s process doesn’t have it. Give the process that variable (a container’s environment, a Kubernetes Secret), or have the config name a file instead (dsn: { file: secrets/shop.dsn }). For link.identity, the message says to put the output of midplane enroll in the variable.

Cannot read config

cannot read config /etc/midplane/midplane.yaml: the file --config names is missing or unreadable. In Docker, mount the folder that holds it, and let the image’s user (uid 1000) read it.

The listen host is not loopback, so TLS is required

Add a certificate (tls), or keep the gateway on 127.0.0.1 behind your TLS proxy.

Midplane needs Node 24.16 or newer

midplane needs Node 24.16 or newer; this is Node 22.12.0. Upgrade Node (node --version prints it). The image is for servers: on your computer it needs a TLS certificate.

Local mode over stdio needs a token in MIDPLANE_TOKEN

--stdio needs a token in MIDPLANE_TOKEN: the MCP client started midplane local --stdio without one. Add the token midplane token printed to the client’s entry for the gateway, as the variable MIDPLANE_TOKEN (local mode).

The localhost URL does not resolve

Some Linux and WSL setups don’t resolve *.localhost. Add the gateway’s name to /etc/hosts: 127.0.0.1 gw-k3m9x2qa.localhost.

Cannot reach the relay

A gateway behind the relay connects out to the relay of its region, such as relay.eu.midplane.app, on port 443. The setup step’s checklist shows how that goes as Relay · connected, and the Gateways page as Relay: connected. Before the first connection they say connecting, and otherwise the relay’s refusal, below. Until it first connects, the gateway can’t get its certificate, so agents can’t reach it; it keeps trying, waiting up to a minute between tries, and logs relay connection failed each time with the status or code. A gateway that connected before keeps enforcing your policies meanwhile (when the relay is down).

Midplane Cloud has no relay

Midplane Cloud at https://… has no relay: set the gateway up at a URL of your own, with --url (or MIDPLANE_URL), from setup. The cloud you set up with has no relay in its region, so a gateway there needs your own URL. Nothing was written, and the token is unused.

Midplane Cloud did not say where its relay is

Midplane Cloud at https://… didn't say where its relay is (503): try again later, from setup: the cloud’s answer had no relay in it, as when it is being deployed. Run setup again, or start the container again, in a few minutes. Nothing was written, and the token is unused.

The relay cannot be reached

Relay: can’t reach it, with why, such as connection timed out (ETIMEDOUT). The gateway couldn’t open a connection to the relay on port 443. Check that its host may connect out on port 443 to the relay’s name, and that the name resolves there (getent hosts relay.eu.midplane.app). A proxy that inspects TLS breaks the connection: let the gateway reach the relay without it. Relay: refused its link token (401). The relay didn’t accept the token the gateway got from Midplane Cloud, even a fresh one, as when the gateway has just been revoked. Check the Gateways page: a revoked gateway can’t be reached at its Midplane URL again, so set up a new one with a new token.

Midplane holds no relay URL for this gateway

Relay: refused: Midplane holds no relay URL for this gateway (403). The gateway’s config has relay, but it didn’t get a Midplane URL when it joined the project, or an owner or admin removed it on the Gateways page. Only joining gives a gateway one: set up a new gateway behind the relay with a new token.

Too many idle connections

Relay: refused: too many idle connections, from replicas of this gateway (429). The relay holds at most 8 idle connections per gateway, and each copy of a gateway keeps 4, so a third copy is refused. Run at most two copies of one gateway behind the relay; for more, give the gateway your own URL. Relay: not tried: the gateway couldn’t get a link token from Midplane Cloud. The gateway asks Midplane Cloud for the token it opens its connections with, and that failed: see cannot reach Midplane Cloud.

The certificate cannot be fetched through the relay

Let's Encrypt couldn't fetch the challenge for gw-….eu.midplane.app through the relay, as the gateway’s last log line at its first start, with what Let’s Encrypt said. Its check of the gateway’s name didn’t reach the gateway, as when the gateway lost its connections to the relay meanwhile. The gateway tries again at its next start, which Docker makes on its own under --restart unless-stopped, with no new token.

An agent cannot connect at the Midplane URL

The agent’s client reports that the connection closed during the TLS handshake, after about 5 seconds or at once. The relay had no connection from the gateway to pass the agent’s connection to:
  • For a gateway it knows, the relay waits up to 5 seconds for an idle connection from the gateway, then closes the agent’s connection without an answer. The gateway is down, or isn’t connected to the relay.
  • For a name no gateway holds, such as a revoked gateway’s, it closes the connection at once.
Nothing reaches the gateway, so the Query log shows nothing. On the Gateways page, the gateway should be enforcing, with Relay: connected. Not responding means it stopped or can’t reach Midplane Cloud: check that it runs, and its log. A relay refusal has its heading above. Check too that the agent has the URL exactly as the Gateways page shows it.

Connecting to a database

Test connection on the Gateways page shows each database’s id with failed and a code, such as shop failed (28P01), and the gateway’s log has the full message. From 0.22.0 the gateway keeps running and retries, and the Gateways page and the setup step say why beside the database: shop · can't connect: password authentication failed (28P01). Earlier versions exit at start.

Connection refused (ECONNREFUSED)

Nothing listens at that host and port. In a container, localhost is the container itself.

Host not found (ENOTFOUND)

The host name doesn’t resolve where the gateway runs, often a private name of another network. Run the gateway inside that network.

Host not found (EAI_AGAIN)

The DNS server didn’t answer for now. The gateway retries; check the host’s DNS if it lasts.

Connection timed out (ETIMEDOUT)

A firewall or security group drops the connection, or the database is on another network.

Connection timed out (TIMEOUT)

Nothing answered within 10 seconds. Same causes as above, or a Neon compute waking up.

Password authentication failed (28P01)

Wrong user or password. Percent-encode special characters (@ is %40). On Supabase’s pooler, the user is midplane_gateway.<project-ref>.

The server refused this role or host (28000)

No pg_hba.conf entry allows this host and role, or the server requires TLS: add sslmode=verify-full. A role without LOGIN is refused the same way.

Database does not exist (3D000)

The database name at the end of the connection string is wrong. It’s the Postgres name, not the id in Midplane.

Permission denied (42501)

The role lacks CONNECT or USAGE: run the role SQL.

Postgres is starting up or shutting down (57P03)

The gateway tries again.

Certificate not trusted (SELF_SIGNED_CERT_IN_CHAIN)

The provider signs with its own CA. Name it with sslrootcert (TLS). A self-signed certificate reports DEPTH_ZERO_SELF_SIGNED_CERT.

Certificate is for another host (ERR_TLS_CERT_ALTNAME_INVALID)

Connect by the host name the certificate names, not an IP address or an alias.

On the dashboard

No catalog yet

No gateway has sent this database’s tables. The line under it says which gateways list the id under databases:, and whether they reach the database. A gateway reads its config at start, so restart it after you change the config. If a gateway reaches the database and it still has no catalog, press Refresh on the policy page.

No gateway serves it yet

No gateway’s config lists this database id. Add it under databases: in the config of a gateway that can reach the database, and restart that gateway (adding databases).

No live gateway serves it

Every gateway whose config lists this database id is Not responding: none has synced for three minutes. The line names each one. Check that they run, and their logs.

In its config, not in this project

The gateway’s config lists a database id the project doesn’t have: a database to add, or a typo. An owner or admin presses Add beside it to add the database with that id; the gateway then sends its tables. For a typo, correct the id in the config and restart the gateway.

Not in its config

The setup step’s checklist shows this when the project has a database that this gateway’s config doesn’t list. Add it to the config if this gateway should serve it. When another gateway serves it, the line says so and there is nothing to do.

Catalog read, differs from the one shown in the policy editor

This gateway read other tables for the id than the policy editor shows, which are the last ones any gateway sent. After a schema change it passes once every gateway has read the database again, within a few minutes. If it stays, the gateways’ connection strings for this id point at different databases.

Not connected yet

The gateway joined the project but hasn’t synced with Midplane Cloud yet: it stopped after joining, or it can’t reach the cloud. Start it, and read its log (cannot reach Midplane Cloud).

Waiting for a policy

The gateway connected but has no policy yet. If it stays, its log says why (sync failed).

Halted

The gateway got a policy it can’t enforce, and refuses every call. The reason shows on the Gateways page: add mask_salt to its config, or upgrade the gateway.

Refusing calls

The project is paused.

Not responding

No sync for three minutes, or no answer to Test connection. Check that the gateway runs, and its log.

Not registered

A URL added to the config after enrollment works once an owner or admin presses Register on the Gateways page.

Another gateway answers on it

Another gateway holds that URL. Revoke it, or use another URL.

It does not send its query log

The gateway is older than 0.21. Upgrade it.

Its audit log never reached Midplane Cloud

The gateway’s file lost events before they were sent. Check the file with export and verify.

Its audit log went backwards, or held two versions of one event

The audit file was restored, copied or rewritten, or two processes share it. Give each linked gateway a file of its own (one linked gateway per file). Nothing is lost: backups.

What an agent is told

The audit log cannot be written, so nothing was run

The audit log can't be written, so nothing was run. Every statement is recorded before it runs. The gateway couldn’t record the statement before running it: the disk that holds audit.file is full or read-only. Free space on it, or make it writable (the file).