# Troubleshooting

## "Didn't open its port in time"

The container started, but nothing answered on the port the service expects. Usually the app listens on another port:

- Set **Port** under the service's settings to the port your app uses, or make the app listen on `$PORT`.
- Check **Logs**: a crash on start shows there.
- Slow starters (big runtimes, migrations on start) may need longer than the wake allows: make startup lighter or keep the service running.

## "The new version didn't become ready"

A deploy started the new version next to the running one, and it never answered, so the running one was kept (your site stayed up). The failed deployment in **Deployments** says which of these it was, and shows what the app last printed:

- **Nothing on its port**: the app listens on another port (it's named, if so), only on localhost, or takes longer than 3 minutes to start. On a service's first deploy, a port it's seen listening on is set for it and it deploys again by itself.
- **Health check**: the **health check path** returns an error or doesn't exist. Open it on the running version to compare, or clear the field.
- **The app stopped**: it crashed on start. Its last output is right there (often a missing variable or secret: when it says which, the failure names it and how to set it, `alf env set --secret NAME`).

Fix the cause and press **Deploy**. See [When a deploy fails](/docs/deployments#when-a-deploy-fails).

## Can't connect to a public port

Press **Test** next to the port (Networking → Public ports):

- "No answer": something in front of the server drops it. That's on Alf's side: write to contact@runalf.com with the port.
- "The server refused the connection": the service isn't running there right now (asleep, or its deployment failed), or the server is being updated. Check the service, and try again in a minute.
- Reachable, but your client is cut off at once (`ECONNRESET`, "connection closed"): your address isn't on the port's allowlist. Look at **Turned away lately** under the port: the address you just tried from is there. Press **Allow** next to it. (Often it's your IPv4 address while the list has your IPv6 one.)
- Connected, then an error from the database: that's the database talking, e.g. a wrong password or `pg_hba.conf` not allowing the user.

See [Databases and other TCP services](/docs/tcp-ports).

## A build failed

Open the deployment in **Deployments** for its log. For the usual causes the failure says what went wrong and what fixes it (so does `alf deploy`, and `alf doctor` afterwards):

- A file the Dockerfile copies wasn't sent: `.gitignore` or `.dockerignore` leaves it out, or it isn't in the repository. `alf deploy` names the line that leaves it out.
- The lockfile doesn't match `package.json` (or `pyproject.toml`, the Gemfile, `composer.json`, `go.mod`): install here and commit the lockfile it writes.
- A `build` or `start` script the Dockerfile runs isn't in `package.json`.
- A dependency needs a newer Node.js, Python or Go than the image has: use a newer base image.
- The base image doesn't exist: check the `FROM` line's name and tag.
- "there is no Dockerfile": check **Dockerfile** and **Build directory** under settings (paths are from the root of the pushed code: in a git repository, the repository's root).
- Other errors in your build steps show as in `docker build`.

## Not sure what's wrong

`alf doctor` (in the app's directory, or with its name) says what Alf knows about a service: a failed deploy and why, running out of memory, a full volume, its error rate, domains that don't work, missing variables. Each finding with what to do next. Agents get the same from `get_service` with `diagnose: true`.

## "The server this runs on can't do this yet"

The server the service runs on doesn't have the version a feature needs yet. Servers update themselves within minutes of a release: try again shortly. If it stays, write to contact@runalf.com.

## No code has been pushed to this service yet

A service built from code waits for its first push: **Deployments → Push its code**, or the [deploy command](/docs/deploying-code) with `--service`.

## The deploy command says the code is too large

It sends what git tracks (or, outside a repository, everything but `.git` and `node_modules`). Build output, dependencies and data files usually don't belong in the build: add them to `.gitignore`.

## A service can't reach another one that sleeps

Calls by name from inside the project wake a sleeping service, like a visitor does. If they fail instead ("connection refused", "could not resolve"), open the sleeping service's **Networking** tab: it says whether calls from inside wake it. They don't when its server's smartalfred-server is too old, or private networking isn't working there (the **Servers** page shows why). Until that's fixed: set the service to **Keep running**, or call its public address.

## "No server has room for another service right now"

Servers keep room free for sleeping services to wake into and for each other's services when one fails, so a busy server takes no new services until its load is down. Creating a service is refused when every server in its regions is in that state.

Choose another region or **Anywhere** under **Scaling → Regions**, or try again a little later; what already runs isn't affected. See [When a server is full](/docs/capacity#when-a-server-is-full).

## "Your free $5 is used up" or "An invoice is unpaid"

Creating and deploying wait for billing to be sorted out: add a payment method, or settle the open invoice, under **Billing**. Everything that runs keeps running meanwhile. See [Pricing, usage and billing](/docs/usage).

## A service keeps restarting

A container that uses more memory than it has is stopped and started again. Its **Overview** says when it has been above 90% of its memory, and channels that listen for "nearly out of memory" hear about it. Give it more memory under **Scaling**; the standard is 512 MB.

## A visitor sees an Alf page instead of the app

When an app can't be served, its visitors get a short page that says why and, under **Is this your app?**, where to look. Pages for things that pass try again by themselves every few seconds. Programs (an API client, `curl`) get the same as JSON or plain text, with the reason in the `X-Smartalfred-Page` header.

| Page | Status | What it means, and what to do |
|---|---|---|
| **There's no app at this address** | 404 | Nothing is deployed at that hostname. Check the service's address (it changes when the service, the project or the organization is renamed), or the **Domains** tab for a domain of your own. |
| **This app isn't deployed yet** | 503 | Its first version is still being built or fetched. **Deployments** shows how far it is, or why it failed. |
| **This app is taking too long to wake up** | 503 | It was asleep and didn't open its port in time. Once is nothing; if it keeps happening see ["Didn't open its port in time"](#didn-t-open-its-port-in-time) above, or give it a bigger size. |
| **The app didn't answer** | 502 | It runs but didn't respond: it listens on another port than the service's, only on `127.0.0.1`, crashed while answering, or took too long. Its logs say which. |
| **This app isn't running yet** | 503 | It isn't on a server yet. If every server is full, it's placed as soon as one has room: see [When a server is full](/docs/capacity#when-a-server-is-full). |
| **This app can't be reached right now** | 503 | Its server isn't connected. [status.runalf.com](https://status.runalf.com) shows whether something is wrong; services without a volume move to another server after about a minute. |
| **This app is paused** | 402 | Alf paused the organization's apps, usually over billing. See **Billing**. |

## A custom domain stays "Waiting for DNS"

- The CNAME must point at `domains.smartalfred.com`; **Check** shows what your DNS says now.
- On Cloudflare, the record must be **DNS only**.
- Root domains need ALIAS/ANAME or CNAME flattening.
- New records can take a few minutes, sometimes longer, to be visible.

## Services can't reach each other

- Use the service's short name and the container port: `db:5432`, not the public address.
- Services must be in the same project.
- Across servers, UDP 51820 must be reachable between them; the Servers page shows if the private network is off and why.

## An agent says it may not do something

- "This token is read-only": it needs read & deploy access.
- "may not run commands": an admin must allow `exec` and sessions for it.
- An `approval_id`: the project needs approvals; see **Agents → Waiting for approval**.
- A limit: the message names it.

## Still stuck?

Check [status.runalf.com](https://status.runalf.com), or write to contact@runalf.com.