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. Ifmidplane 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, solocalhost 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 tolink.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 asrelay.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 asconnection 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.
The relay refused its link token
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 hasrelay, 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.No link token for the relay
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.
Connecting to a database
Test connection on the Gateways page shows each database’s id withfailed 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)
Nopg_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 lacksCONNECT 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 withsslrootcert
(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 underdatabases:, 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 underdatabases: 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: addmask_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).