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

```bash theme={null}
# For ECR - verify credential helper is installed
which docker-credential-ecr-login

# Manual ECR login (for testing)
aws ecr get-login-password --region eu-west-3 | docker login --username AWS --password-stdin <2501-ecr-registry>

# For Generic registry
docker login <registry-url>
```

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

# Reinitialize
./2501-infra init --force --no-postgres
./2501-infra deploy
```

***

## Feature Toggles Reference

Feature toggles control various system behaviors. Modify them via SQL:

```sql theme={null}
UPDATE "FeatureToggle" SET enabled = true WHERE key = 'toggle_key';
```

### Integration Toggles

| Toggle Key            | Description                       | Default    |
| --------------------- | --------------------------------- | ---------- |
| `enableElasticSearch` | Enable Elasticsearch integration  | ❌ Disabled |
| `enableDockerSwarm`   | Enable Docker Swarm orchestration | ❌ Disabled |

### Security & Logging Toggles

| Toggle Key                   | Description                      | Default    |
| ---------------------------- | -------------------------------- | ---------- |
| `enableSecureLogs`           | Enable secure logging            | ❌ Disabled |
| `enableEmbeddings`           | Enable embeddings for RAG        | ❌ Disabled |
| `enableCredentialProcessing` | Enable credential processing     | ❌ Disabled |
| `enableCommandVerification`  | Verify commands before execution | ❌ Disabled |
| `enableLogLlmInputAndOutput` | Log LLM input/output             | ❌ Disabled |

### Experimental Toggles

| Toggle Key                           | Description                              | Default    |
| ------------------------------------ | ---------------------------------------- | ---------- |
| `enableSlowInference`                | Reduce parallel tasks for slow inference | ❌ Disabled |
| `enableOperationalRulesVerification` | Enable operational rules verification    | ❌ Disabled |

***

## Support

For issues or questions:

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