Skip to main content
Start with the logs. Most problems say their cause there in one line.

​
No sign-in code arrives

With npx supabase start, no email leaves your computer. Every code lands in Mailpit, at http://localhost:54424. With open source Supabase on your server, emails go through the SMTP server of supabase-stack/.env, and docker logs supabase-auth shows why one failed. With a project on supabase.com, check in this order:
  1. The template. The email must carry the code, {{ .Token }}. Supabase’s default templates only carry a link, so the email arrives without a code. Paste the Rerun template into Magic Link, Confirm signup and Change Email Address.
  2. The mailer. Supabase’s own mailer sends a handful of emails an hour, and only to the members of your Supabase organization. Set up your own SMTP server in Authentication > Emails > SMTP Settings.
  3. The logs. Logs > Auth in the Supabase dashboard shows each email Supabase tried to send, and why it failed.
  4. The spam folder, with the built-in mailer especially.
If the code arrives but is refused, it may have expired (15 minutes with the Rerun settings), or Email OTP Length is not 6.

​
The sign-in dialog fails, or “Anonymous sign-in failed” in the logs

A visitor starts as an anonymous user, and signing up turns that user into an account. On a project on supabase.com, turn on Allow anonymous sign-ins in Authentication > Sign In / Providers, and keep Confirm email on.

​
”permission denied” from Postgres

The database is missing migrations. The schema is built by every file of supabase/migrations, in order, and a single missing one leaves tables or grants out.
With open source Supabase, add --db-url and the address from Install to migration list and to db push --yes. After git pull, run it again: a release can add migrations. Also check that SUPABASE_SECRET_KEY holds the secret key (service_role), not the publishable one. The app does its server-side work with it.

​
The app cannot reach Supabase on your machine

Symptoms: the board does not load, and the app logs show ECONNREFUSED on port 54421. Inside the app container, localhost is the container itself, not your machine. Start with the profile that adds the relay:
And keep NEXT_PUBLIC_SUPABASE_URL=http://localhost:54421, the address your browser uses too.

​
Tables are missing after npx supabase start

If the first start failed partway, the next one reuses a database that never received the migrations: pages fail with relation "public.services" does not exist. Rebuild it, which erases its data:

​
No sign-in code in the email

With open source Supabase, the default emails carry a link and no code. Serve the templates of your clone to the auth service, as in Install.

​
A Supabase service dies during the build

The server ran out of memory: dmesg | grep -i "out of memory" confirms it. Add swap or memory, as in Install, then restart Supabase with docker compose up -d in its folder.

​
The build fails for lack of memory

Symptoms: Killed, exit code 137, or JavaScript heap out of memory while building the app. The app build needs about 6 GB of memory. In Docker Desktop, raise it in Settings > Resources > Memory. On a small VPS, add swap, or build the image on another machine.

​
Changing .env changed nothing

Values starting with NEXT_PUBLIC_, and ADMIN_EMAILS, are baked into the app when it is built. Rebuild:
Any other value only needs docker compose up -d, which recreates the containers with the new .env.

​
”This workspace has no server yet”, or a coworker “could not be built”

The engine docker compose started already belongs to another workspace. It goes to the first workspace that needs an engine, which can be a workspace you created while trying things out. Either pair a server for this workspace, or free the compose engine in Supabase Studio (see Common tasks) and place a coworker again.

​
The app cannot reach your server

The pairing says: “The app cannot reach your server at …”. The app checks the address before attaching the server, from inside its own container.
  • The address. Is it the one in the message? Without RERUN_PUBLIC_URL, the app guesses from where the request came from, which is wrong behind a proxy, a NAT or a tunnel. Set RERUN_PUBLIC_URL in the command.
  • The port. The command publishes the engine on port 3000 with -p 3000:3000. Check nothing else holds it.
  • The firewall. Open port 3000 to the app’s machine only, or use HTTPS behind a proxy. See Networking.
  • Tailscale. Both machines on the same tailnet, and the server’s Tailscale IP as the address, not its MagicDNS name.
Run curl http://<address>/health from the app’s machine: it must answer before the pairing can.

​
The server cannot reach the app

The server logs say pairing not done yet a few times, then pairing failed. RERUN_HUB_URL in the command is your NEXT_PUBLIC_APP_URL. When it is http://localhost:3000, a server elsewhere cannot reach it, and a container on the same machine reaches itself. Give the app an address the server can reach, rebuild, and click Add server again.

​
The pairing token expired, or was already used

A token works once, for 15 minutes, for one workspace. Click Add server again for a new command, then:
and run the new command. The volume keeps its data.

​
A coworker answers “Set OPENROUTER_API_KEY to run the Rerun models”

The coworker is on a Rerun model, and the app has no OpenRouter key. Either:
  • put your key in OPENROUTER_API_KEY in .env and run docker compose up -d, or
  • connect another provider in AI providers and pick it in the coworker’s model picker. See AI models.

​
The Foreman does not answer

The Foreman runs on OPENROUTER_API_KEY only. Set it and run docker compose up -d. If it is set, look for [llm] or OpenRouter errors in docker compose logs app: an empty balance or a spending limit on the key stops it too.

​
A Composio app does not connect

“Composio connections are not configured on this server”: set COMPOSIO_API_KEY and run docker compose up -d. An error from Composio when you click Connect: the service has no auth config of yours yet. The ids shipped in the catalog are empty. Create one in Composio and write its id on the service. See Composio.

​
The screen does not show

The browser opens a coworker’s screen directly on the server’s address, over ws:// or wss://.
  • The engine started by docker compose needs RERUN_ENGINE_BROWSER_URL: its https domain on a server, as in On a server.
  • Your browser must reach the server. On Tailscale, the person watching must be on the tailnet too.
  • HTTPS on both sides. When the app is on https://, the server must be too, or the browser blocks the connection. Put it behind Caddy.
  • The screen was turned off with RERUN_DESKTOP=off on the server.

​
Web search does not work

Coworkers search the web through Brave. Set BRAVE_SEARCH_API_KEY and run docker compose up -d.

​
An engine misbehaves after an update

Check its data-dir. The command changes nothing:
/health also reports dataVersion against dataVersionTarget. An engine older than its data-dir leaves the data untouched and boots: update the engine image rather than restoring an older archive.

​
Still stuck

Open an issue on GitHub with what you ran, what you expected, and the output of docker compose logs --since 30m app engine. Remove keys and tokens first.