Troubleshooting
The problems people hit most often with zap.ts, and what to do about each one.
This page lists the problems people hit most, with the fix for each.
The app cannot reach the database
You see an error about a connection being refused on port 5432.
Almost always, Docker is not running. Check:
docker compose psIf the list is empty, start the services:
docker compose up -dIf Postgres is listed but says unhealthy, wait a few seconds and look again.
It takes a moment to become ready the first time.
On a Mac with Colima, docker compose ps
fails with a message about the daemon when Colima is stopped. Colima does not
start by itself after you restart your Mac:
colima startIf something else on your computer already uses port 5432, stop that program,
or change the port in docker-compose.yml.
The tables do not exist
You see an error saying a relation or a table was not found.
The database is running but empty. Create the tables:
pnpm run db:migrateThen add the example data:
pnpm run db:seedThe build stops and names a setting
You see a message saying a required value is missing.
This is varlock doing its job. It checks your settings before the app starts, so the app does not fail later with a confusing error.
Find out where that value should go:
pnpm run env:webThis prints every value the web app needs and where each one comes from. Put
your real value in a .env.local file, next to the .env.schema that
declares it. See Environment.
I get no email
Nothing is broken. In local development, email does not leave your computer.
Open localhost. That is Mailpit, and your message is waiting there.
If Mailpit is empty, check that Docker is running.
Uploads fail
Check that MinIO is running:
docker compose ps minioOpen localhost and sign in with minioadmin for
both the username and the password. You should see a bucket named zap.
If the bucket is missing, restart the services. A helper container creates it on startup.
Checkout does not work
The plan IDs that ship with zap.ts are fake examples. Checkout cannot work until you replace them.
Copy the real IDs from your payment company’s dashboard into
packages/billing/src/plans.ts. See Billing.
I am signed in to the app but not the back office
That is correct behaviour, not a bug.
The back office keeps its own separate sign-in. Sign in again at the admin
app. Your user also needs the admin role. See Admin.
A port is already in use
Each app has its own port: web 3000, marketing 3001, docs 3002, admin 3003, emails 3004, api 8787.
If one is taken, another app of yours is probably still running in a different
terminal window. Close it, or change the port in that app’s vite.config.ts.
Types are wrong after I changed the database
Your editor still shows the old columns.
Regenerate and apply:
pnpm run db:generate
pnpm run db:migrateIf your editor still disagrees, restart the TypeScript server in your editor. It caches types.
Something changed in a package and my app does not see it
Reinstall so pnpm relinks the folders:
pnpm installIf that does not help, the build cache is stale. Delete the dist folder of
that package and build again.
The end-to-end test refuses to start
You see:
TEST_DATABASE_URL is required to run the end-to-end testSet it and run again:
export TEST_DATABASE_URL=postgresql://postgres:postgres@127.0.0.1:5432/postgres
pnpm run test:e2eStarting again from a clean database
This deletes all your local data. Your code is not touched.
docker compose down -v
docker compose up -d
pnpm run db:migrate
pnpm run db:seedRelated
- Quickstart — the first run
- Local development — day-to-day work
- Environment — settings and keys
- Testing — running the tests