Troubleshooting

Common errors and how to fix them.

Common errors you may encounter and their solutions. When in doubt, run devto doctor first.

"No project linked in this directory"

devto could not find a .devto.json file in the current directory or any parent directory.

Fix

bash
# Navigate to your project root and link it
cd /path/to/your/project
devto init

"Missing or malformed Authorization header"

Your API key is not set or is invalid. This usually means you have not run devto login or your key has expired.

Fix

bash
# Re-authenticate
devto login
# Or manually check your config
cat ~/.devto/config.json

"Workspace token invalid"

Your project tracker API token (e.g., Jira API token) has expired or been revoked.

Fix

"Can't reach database server"

The devto cloud backend is unable to connect to its database. This is a Railway networking issue on our side.

Fix

  • -Wait a few minutes and retry — Railway occasionally has brief connectivity interruptions
  • -Check status.railway.app for platform-wide issues
  • -If the issue persists, contact us at hello@devto.ai

"Rate limit exceeded"

You have exceeded 60 API requests per minute. This is a safety limit to protect your project tracker.

Fix

Wait 60 seconds and retry. If you consistently hit this limit, consider using bulk operations (bulk_create_tasks, bulk_update_tasks) instead of individual calls.

"Free tier limit reached"

You have used all 75 write actions for the current month on the Free plan. Read operations (get_*, list_*, search_*) are not affected.

Fix

  • -Upgrade to Pro for unlimited actions
  • -Wait until your monthly cycle resets
  • -Check your usage with devto status

Understanding devto doctor output

Run devto doctor to get a complete diagnostic report. Each check shows either a green checkmark or a red X with a specific error message and suggested fix.

bash
$ devto doctor
✓ API key valid
✓ Workspace connected (my-team.atlassian.net)
✗ Anthropic key not configured
  → Run: devto config set anthropic-key sk-ant-xxxx
✓ MCP server registered
1 check failed.

The Anthropic key is only required for AI planning (create_plan). All other tools work without it. If you do not need AI planning, you can safely ignore this check.