Troubleshoot Maia

Start every investigation with the exact failing identity and surface: local CLI, dashboard, gateway platform, or scheduled job. The same prompt can follow different configuration and authorization paths.

Run the first checks

maia status
maia doctor
maia logs

The maia command is not found

The installer normally puts the launcher in ~/.local/bin. If that location cannot be written, it automatically uses ~/.maia/bin; no permission repair or elevated install should be required.

1. Reload the shell with source ~/.bashrc or source ~/.zshrc.
2. Confirm that ~/.local/bin or ~/.maia/bin is in PATH.
3. Re-run the installer as a repair if the launcher is missing.

The model provider rejects requests

• Run maia model and confirm the selected provider and model.
• Re-authenticate or replace the API key through Maia's managed key flow.
• Confirm that the account can access the selected model.
• Check provider quota, billing, organization, and regional restrictions.

The dashboard does not open

maia dashboard --status
maia dashboard --stop
maia dashboard --no-open

Check whether another process is using the selected port. Use --port to choose a different local port.

A gateway user is blocked

1. Confirm that the platform identity is admitted or paired in Gateway.
2. Open Governance and look for Pending Governance.
3. Add the exact platform:user_id with at least one role.
4. Ask the user to run /whoami. Governance membership and file-policy changes apply when the user's next gateway request starts; a new thread or gateway restart is not required.

A user has the wrong access

• Verify the stable identity, not the display name.
• Inspect roles, teams, role hierarchy, and individual exceptions.
• Inspect the most specific matching folder policy.
• Retry in the same conversation after saving. If behavior differs, check sandbox health rather than opening a new session as a workaround.
• Check the audit log for a policy decision.

A permitted edit reports secure execution unavailable

secure_execution_unavailable means the grant is still valid, but Maia could not start the Docker security boundary required for terminal or code execution. Maia does not run the command on the host and does not change the file.

1. Open Governance and check the Secure execution status.
2. Run docker version on the machine and inside the same WSL distribution that runs Maia.
3. On Windows, open Docker Desktop Settings → Resources → WSL Integration, enable the Maia distribution such as Ubuntu, and choose Apply & restart.
4. After Docker is ready, retry the same request. No additional file grant, new thread, or gateway restart is required.

A cron action runs twice

If Hermes data was imported, compare both schedulers:

maia cron list
hermes cron list

Pause the duplicate. Also confirm that only the intended gateway and scheduler service are enabled.

Prepare a support package

Record the Maia version, operating system, installation method, exact command or platform, timestamp, affected identity, expected behavior, and relevant redacted logs. Never include API keys, tokens, passwords, or raw customer data.