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
# 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)
# 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 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 |
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:
- Check logs and health endpoints
- Verify configuration against this guide
- Contact 2501.ai support
