Troubleshooting

When a deployment fails, FASTBASE explains the likely cause in plain language on the deployment page and in the CLI. The raw log is always one click away. Ask the AI Engineer “Why did my deployment fail?” for the same explanation in context.

Deployment problems

You see	Cause	Fix
Some required settings are missing	A variable in `.env.example` has no value and FASTBASE cannot generate it	Add it under Environment, or `fastbase deploy --env KEY=VALUE`. Mark it `# optional` if the app can run without it.
FASTBASE could not understand this project	No `package.json`, `index.html` or `Dockerfile` in the uploaded folder’s root	Deploy the project root, not a parent folder.
The lockfile does not match package.json	Dependencies changed without updating the lockfile	Run your package manager’s install locally and deploy again.
A package.json script is missing	No `build` or `start` script	Add it, or set the command under Settings → Advanced.
TypeScript found an error in your code	The build runs your type check	Fix the reported line.
A dependency is missing	Imported but not in `package.json` — or in `devDependencies` while needed at runtime	Add it to `dependencies`.
A file your code imports is missing	Often a file name whose letter case differs, or a git-ignored file	Match the exact name; make sure the file is uploaded.
The app ran out of memory	The build or the app needs more memory	Reduce build memory (for example disable source maps) or raise the limit on your installation.
The app started but never answered	The server does not listen on `PORT`, or the health path returns a 5xx	Listen on `process.env.PORT`; set a health path that works without login.
The app tried to use a port that is already taken	A hard-coded port	Use `process.env.PORT`.
Database migrations failed	The migration command exited with an error	Fix the migration. The previous version stays live.
A database table is missing	No migration created it	Add a `db:migrate` script so tables are created on every deploy.
This project only has a Dockerfile	The installation runs without Docker	Add a `start` script, or run FASTBASE with `FASTBASE_COMPUTE_PROVIDER=docker`.

The app is live but misbehaves

Logs → Runtime shows what the app prints. Secret values are masked.
Application unavailable (503) — the app keeps crashing. After five crashes in ten minutes FASTBASE stops restarting it. Check the runtime log, then redeploy or Restore last working version.
Application is not responding (502) — it is restarting or overloaded; try again in a moment.
Nothing is deployed here (404) — the address belongs to no live project, or a custom domain is not verified yet.
A changed environment variable has no effect — variables apply on the next deployment. Redeploy.

CLI

Message	Fix
`You are not logged in`	`fastbase login`, or set `FASTBASE_TOKEN`
`Could not reach FASTBASE at …`	Check `--api-url` / `FASTBASE_API_URL` and that the platform is running
`This folder is not linked to a project`	Run `fastbase deploy` once, `fastbase init`, or pass `--project <slug>`
`This token lacks the "…" scope`	Create a token with that scope

Limits

Your … plan's limit for … has been reached — a quota blocks new work of that kind only. Nothing already running is stopped. Upgrade the plan under Settings, or wait for the next month for monthly limits.

Running FASTBASE yourself

Port already in use — change FASTBASE_API_PORT, FASTBASE_WEB_PORT, FASTBASE_PROXY_PORT, FASTBASE_REALTIME_PORT or FASTBASE_EMBEDDED_PG_PORT in .env.
*.localhost does not resolve — browsers resolve it automatically; some command-line tools do not. Use curl -H "Host: myapp.localhost" http://127.0.0.1:8080/.
Stored secrets cannot be decrypted after a reinstall — FASTBASE_MASTER_KEY changed. Restore the original key; it cannot be recovered.
Start from scratch — stop FASTBASE and delete the data directory (.fastbase-data). This deletes every project, database and file on that installation.