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

> Troubleshooting guide and feature toggles reference for 2501

Common issues and solutions for 2501 deployments.

***

## Common Issues

### Registry Authentication Failed

Registry authentication is handled by the CLI on every deploy, so there is no credential helper or `docker login` to fix. If a deploy reports an image pull or authentication failure, confirm the pull-only registry key from 2501 was supplied at install (or that the node's AWS credentials resolve), then re-run the deploy to fetch a fresh token. Run `2501 infra config` to inspect the effective registry configuration.

### Database Connection Failed

```bash theme={null}
# Test connection
psql "postgresql://<user>:<password>@<host>:5432/2501"

# Check DATABASE_URL format
# postgresql://<user>:<password>@<host>:<port>/<database>?schema=public
```

### Services Not Starting

```bash theme={null}
# View logs
docker service logs -f 2501_engine
docker service logs -f 2501_command-center

# Check resources
docker stats
```

### Migration Failed

```bash theme={null}
# Check database is accessible
# Check DATABASE_URL and DIRECT_URL are correct
# Retry deployment
2501 infra deploy
```

***

## Viewing Logs

```bash theme={null}
docker service logs -f 2501_engine
docker service logs -f 2501_command-center

# All services status
docker stack services 2501
```

***

## Health Checks

```bash theme={null}
curl http://localhost:1337/health    # Engine
curl http://localhost:3000/health    # Command Center
```

***

## Reset Everything

<Warning>
  This will delete all data. Only use this for development/testing environments.
</Warning>

```bash theme={null}
# Stop and remove
2501 infra deploy --remove

# Remove volumes (WARNING: deletes data)
docker volume rm $(docker volume ls -q | grep 2501)

# Redeploy
2501 infra deploy
```

***

## Upgrading

There is no separate update command. Run an interactive `2501 infra deploy`: it lists published releases newest-first, and when you pick a version it self-updates its own binary to match (checksum-verified, then re-executed) before deploying. This keeps the CLI in lockstep with the deployed platform version.

To refresh only the CLI binary, re-run the installer. It is idempotent and never touches an existing workspace.

***

## Feature toggles

Toggle reference and CLI moved to its own page — see [Feature Toggles](/0.7/deployment/feature-toggles).

***

## Support

For issues or questions:

1. Check logs and health endpoints
2. Verify configuration against this guide
3. Contact 2501.ai support