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
Services Not Starting
Migration Failed
Viewing Logs
Health Checks
Reset Everything
This will delete all data. Only use this for development/testing environments.
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.
Support
For issues or questions:
- Check logs and health endpoints
- Verify configuration against this guide
- Contact 2501.ai support
