Troubleshooting

When something breaks, Alaf Server has almost always already told you why — the trick is knowing where it wrote it down. This page is the starting point: it shows you the handful of places the real answer lives, and one habit that solves most problems on its own.

Where the useful information lives

There are only a few screens you ever need. Match your situation to the right one:

The live build screen

This is the page you watch during a deploy — like watching the oven through the glass door. It streams the build as it happens and, when it finishes, hands you the live URL. If a build fails, this is the first place to look: the failing command and its error are in the last lines before the stream stops. See the deploy wizard for a tour of it.

The project Logs tab

Once an app is live, open it and pick Logs. You get two sub-tabs you switch between:

• Server — its panel is headed HTTP Request Logs: one line per incoming request (method, path, status code, response time, country, and size). Great for "is anything even hitting my app?" and for spotting a flood of 4xx/5xx responses. (For a static site with no runtime, this tab is relabeled Requests.)
• Terminal — your app's own stdout/stderr, streamed straight from the running container. This is where a crash, a stack trace, or a "listening on port…" line shows up.

Use the Copy or Download buttons in the header row to grab the logs when you want to save them or ask for help. The full walkthrough is in Logs & monitoring.

The CLI

Everything above has a terminal equivalent:

# Snapshot of a deployment's logs
alaf server logs <deploymentId>

# Stream them live until the deployment finishes
alaf server logs <deploymentId> --follow

# Just the last 50 lines
alaf server logs <deploymentId> --tail 50

Two commands answer "is my setup even OK?" before you go hunting further:

# Check config, active login, whether the API is reachable, and your runtime
alaf server doctor

# Health + mode (self-hosted vs cloud) of the API you're pointed at
alaf server status

alaf server doctor prints a checklist with a green ✓, yellow !, or red ✗ next to each of config, context, api, node, and bun — so a red line tells you exactly which part is wrong. Full command details live in the CLI reference.

How to read an Alaf Server error

Alaf Server errors are short and structured on purpose — they're not meant to be scary.

In the dashboard, failures show up as a toast (a small popup) with a message, and — for anything that was streaming — as a red line in the build screen or Logs terminal. Read the message; it's the same text the server sent.

From the API or CLI, every error comes back as a small JSON object with two fields you care about:

{ "error": "human-readable message", "code": "MACHINE_CODE" }

• error is the sentence to read.
• code is a stable label you can search for. Bad input is reported as code: "VALIDATION_ERROR" with a details object naming the exact fields that failed.
• The HTTP status tells you the category at a glance: 400 bad request, 401 not logged in, 403 not allowed, 404 not found, 409 conflict (something already exists / is in use), 500 a genuine server error. A bare { "error": "Internal server error" } with status 500 means the cause is in the server logs, not in what you sent.

Symptom: a deploy failed and you can't tell why

What it means — a command in the build gave up. The line that matters is the last one before the stream stopped, not the wall of output above it.

How to fix

1. Scroll to the bottom of the build screen and read the final red lines out loud — they name the failing step (a missing command, a package that won't install, a port mismatch).
2. If it mentions a missing setting or secret, add it under the project's Configuration tab and redeploy.
3. Still stuck? Press Copy/Download to save the log, then match the message against Troubleshooting → Deployments, which lists the common build and runtime failures with fixes.

Symptom: the CLI can't reach your instance

What it means — the CLI is pointed at an instance it can't talk to: the wrong address, an instance that isn't running, or a login that has expired.

How to fix

1. Run alaf server doctor. It checks, in order: your config file, your active context and token, and whether the api answers.
2. If context is yellow with "has no token; run alaf server login", log in again.
3. If api is red, confirm the instance is actually up (alaf server status shows its health and mode) and that the address is the one you expect.

Jump to the right page