Skip to main content

​
Authentication errors

Your session token has expired or is missing.
mage-agent login
This fetches a new token and overwrites the existing config.
The config file at ~/.mage-agent/config.json is missing or malformed.Re-run login to recreate it:
mage-agent login
Or create the file manually:
{
  "cluster_url": "https://your-mage-url",
  "oauth_token": "YOUR_OAUTH_TOKEN"
}

​
MCP / IDE issues

  1. Confirm mage-agent is accessible from the IDE’s runtime PATH — or use an absolute path (see Installation).
  2. Save the MCP config and restart the IDE or agent client.
  3. Test the server directly in a terminal:
mage-agent mcp
If it starts without errors, the issue is the IDE config. If it errors, check authentication first.
The IDE cannot find the executable. Run:
which mage-agent
Copy the full path and use it in your IDE config:
{
  "mcpServers": {
    "mage-agent": {
      "command": "/full/path/to/mage-agent",
      "args": ["mcp"]
    }
  }
}
Run login again — the MCP server may have started before credentials were saved, or the token expired during the session:
mage-agent login
Then restart the IDE to pick up fresh credentials.

​
Sync issues

Conflicts are detected by comparing timestamps on each side. Small clock differences between your machine and the cluster can cause false positives.Check what the conflict looks like before choosing a side:
mage-agent sync-status --local-project-dir ./my-project --format-output human
Then run mage-agent sync and choose r (remote) or l (local) for each affected file.
Only these file extensions are tracked: .py, .sql, .r, .yaml, .yml, .md, .txt.Also check that the files are not inside a hidden directory (.git, .venv) or a __pycache__ folder — those are always excluded.
The state file lives at <local-project-dir>/.mage-agent-sync-state.json. If it is missing, mage-agent treats all files as new and will re-pull the full project on the next sync-project-to-local. Delete it intentionally only if you want a clean baseline.

​
Enable debug logging

Add --log-level DEBUG to any command to see full request/response traces: 
mage-agent --log-level DEBUG sync-status --local-project-dir ./my-project
mage-agent --log-level DEBUG mcp
Or set the environment variable permanently in your shell profile: 
export MAGE_AGENT_LOG_LEVEL=DEBUG

​
Still stuck?

Open an issue at github.com/mage-ai/mage-agent and include the debug log output.