Common issues and solutions for 2501 deployments.
Common Issues
Registry Authentication Failed
# 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
# Test connection
psql "postgresql://<user>:<password>@<host>:5432/2501"
# Check DATABASE_URL format
# postgresql://<user>:<password>@<host>:<port>/<database>?schema=public
Services Not Starting
# View logs
docker service logs -f 2501_engine
docker service logs -f 2501_command-center
# Check resources
docker stats
Migration Failed
# Check database is accessible
# Check DATABASE_URL and DIRECT_URL are correct
# Retry deployment
./2501-infra deploy
Viewing Logs
docker service logs -f 2501_engine
docker service logs -f 2501_command-center
# All services status
docker stack services 2501
Health Checks
curl http://localhost:1337/health # Engine
curl http://localhost:3000/health # Command Center
Reset Everything
This will delete all data. Only use this for development/testing environments.
# 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 -t swarm --no-postgres
./2501-infra deploy
Feature Toggles Reference
Feature toggles control various system behaviors. Modify them via SQL:
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 |
enablePlugins | Enable plugins system | ❌ 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 |
enableLogLlmUnparsableResponse | Log unparsable LLM responses | ❌ Disabled |
Experimental Toggles
| Toggle Key | Description | Default |
|---|
enableSlowInference | Reduce parallel tasks for slow inference | ❌ Disabled |
enableOperationalRulesVerification | Enable operational rules verification | ❌ Disabled |
enableFunctionFormatVerification | Enable function format verification | ❌ Disabled |
enableFunctionsInTheLastMessage | Enable functions in last message (experimental) | ❌ Disabled |
enableExtraLLMLogging | Enable extra LLM logging (temporary) | ❌ Disabled |
Support
For issues or questions:
- Check logs and health endpoints
- Verify configuration against this guide
- Contact 2501.ai support
