> ## Documentation Index
> Fetch the complete documentation index at: https://docs.2501.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common issues on a 2501 installation, and how to collect logs

The commands use the namespace in `$NS` and, on Docker Swarm, the stack name in `$STACK`: the name you deploy the stack with, `ai-2501` in [Deploy](https://docs.2501.ai/0.19/deployment/docker-swarm.md#deploy), or the CLI's stack name for an installation [moved from the CLI](https://docs.2501.ai/0.19/deployment/migrate-from-cli.md).

## Common issues

### The chart refuses values.yaml

The chart checks `values.yaml` against its schema and names the value it refuses, for example a public registry, an OpenShift installation with the database 2501 provides, or Docker Swarm without `commandCenter.expose.port`. Fix that value and render again. See [values.yaml](https://docs.2501.ai/0.19/deployment/configuration.md).

### Sign-in fails with INVALID\_ORIGIN

Command Center accepts a sign-in only from `https://<commandCenter.host>`, exactly: the browser must open that address, with no port and no other host name or IP address. Open Command Center at that address, or change `commandCenter.host` (`COMMAND_CENTER_HOST` on Docker Swarm) to the name users open.

### Pods wait in CreateContainerConfigError or ContainerCreating

A secret they read does not exist yet. `kubectl -n "$NS" describe pod <pod>` names it. Create it as [Create the secrets](https://docs.2501.ai/0.19/deployment/kubernetes.md#create-the-secrets) shows: the pod starts on its own once it exists.

### Image pull fails

Every image comes from `global.imageRegistry`, by digest. Check that the build's images were copied completely, with every repository under `2501.ai/release/`, and that the registry login secret in `global.imagePullSecrets` exists in the namespace. On Docker Swarm, run `docker login` before `docker stack deploy --with-registry-auth`.

### Database connection failed

```bash theme={null}
psql "postgresql://<user>:<password>@<host>:5432/<database>?sslmode=verify-full"
```

For your own database, `DATABASE_URL` and `DIRECT_URL` in `pg-connection-v1` must reach it; `DIRECT_URL` bypasses any connection pooler. The engine's migration step and the bootstrap log say why they cannot connect.

### Migration failed

The engine applies the migrations before it starts, and Command Center waits for them. Read the engine's migration log, fix the cause, then restart the engine:

```bash theme={null}
kubectl -n "$NS" logs deploy/engine -c migrate
docker service logs "${STACK}_engine"   # Docker Swarm
```

## Viewing logs

```bash theme={null}
kubectl -n "$NS" get pods
kubectl -n "$NS" logs deploy/engine -f
kubectl -n "$NS" logs deploy/command-center -f
kubectl -n "$NS" logs "job/$(kubectl -n "$NS" get jobs -l app.kubernetes.io/component=bootstrap --sort-by=.metadata.creationTimestamp -o name | tail -1 | cut -d/ -f2)"   # the newest bootstrap Job

docker stack services "$STACK"   # Docker Swarm
docker service logs -f "${STACK}_engine"
docker service logs -f "${STACK}_command-center"
docker service logs "${STACK}_bootstrap"
```

### Exporting logs for a bug report

The Command Center's **Debug** page (admin-only) lets you browse structured logs and download them: an NDJSON export of whatever the current filters show, or a bundle with everything about one trace, task or job.

Downloads are **anonymized by default**: IP addresses, hostnames, MAC addresses and emails are replaced with stable placeholders (`[ip-1]`, `[host-2]`, …). The same value always maps to the same placeholder within one file, so a connection chain or a repeated failure stays readable without revealing your infrastructure. Anonymized files carry an `-anon` suffix in their name.

Turn the **Anonymize** toggle off to download the raw records instead - for example when the file stays inside your organization.

## Health checks

```bash theme={null}
kubectl -n "$NS" rollout status deploy/engine
kubectl -n "$NS" rollout status deploy/command-center
curl -f http://<a Swarm node>:<commandCenter.expose.port>/health   # Docker Swarm
```

## Support

1. Check the logs and the health of the services.
2. Check `values.yaml` and the secrets against this guide.
3. Contact 2501 support, with the build you run (the `<build>` of the files you applied) and the logs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.