---
title: Troubleshooting
description: 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:

```bash
docker compose ps
```

If the list is empty, start the services:

```bash
docker compose up -d
```

If 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](https://github.com/abiosoft/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:

```bash
colima start
```

If 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:

```bash
pnpm run db:migrate
```

Then add the example data:

```bash
pnpm run db:seed
```

## The 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:

```bash
pnpm run env:web
```

This 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](/guides/environment).

## I get no email

Nothing is broken. In local development, email does not leave your computer.

Open [localhost:8025](http://localhost:8025). 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:

```bash
docker compose ps minio
```

Open [localhost:9001](http://localhost:9001) 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](/packages/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](/apps/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:

```bash
pnpm run db:generate
pnpm run db:migrate
```

If 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:

```bash
pnpm install
```

If 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 test
```

Set it and run again:

```bash
export TEST_DATABASE_URL=postgresql://postgres:postgres@127.0.0.1:5432/postgres
pnpm run test:e2e
```

## Starting again from a clean database

This deletes all your local data. Your code is not touched.

```bash
docker compose down -v
docker compose up -d
pnpm run db:migrate
pnpm run db:seed
```

## Related

- [Quickstart](/quickstart) — the first run
- [Local development](/guides/local-development) — day-to-day work
- [Environment](/guides/environment) — settings and keys
- [Testing](/guides/testing) — running the tests