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
Exporting logs for a bug report
The Command Center’s Debug page lets you browse structured logs, filter them by trace, task, or job, watch them arrive with a live-tail view, and download them: an NDJSON export of whatever the current filters show, or a bundle with everything about one trace, task or job.
Anyone who can already view logs can also download them — this is not restricted to administrators.
Downloads are anonymized by default: IP addresses, hostnames, MAC addresses and emails are replaced with stable placeholders ([ip-1], [host-2], …). The same value always maps to the same placeholder within one file, so a connection chain or a repeated failure stays readable without revealing your infrastructure. Anonymized files carry an -anon suffix in their name.
Turn the Anonymize toggle off to download the raw records instead - for example when the file stays inside your organization.
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.
Back up PostgreSQL before upgrading. See Upgrading for the backup command and the rollback steps.
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
