Troubleshooting
Quick fixes for common issues. For configuration details, see Settings and Environment variables.
Install issues
- Command not found after install — Ensure the install script added the binary to your PATH. Restart the terminal or add the path manually. See Quickstart for install methods.
- Permission denied — On Linux/macOS, ensure the binary is executable (use
chmod +x) and that you have write access to.maestro/in your project.
Auth and connection errors
If the agent or API reports auth or connection errors, check that your API key or SSO is set correctly in environment variables or in .maestro/. Invalid or expired tokens often cause "401" or "connection refused". See Environment variables and Authentication.
Web app: API or auth proxy errors
- 502 / Bad Gateway on /api/backend or /api/autonomy — The Next.js server cannot reach the FastAPI host. In Docker, confirm
API_INTERNAL_URLuses the service name and port (e.g.http://api:8000), notlocalhostfrom inside the web container. See Web app & API proxies. - Login or OAuth fails in Compose — Set
AUTH_INTERNAL_URLif auth runs as a separate service, and ensure the web container can resolve that host. See Self-hosted deployment. - 404 on an endpoint you expected — Compare your path to OpenAPI; deployments differ by version and configuration.
Gate failures
When a gate fails, the output usually indicates which check failed (e.g. lint, test, contract). Fix the underlying issue (tests, lint rules, or contract definitions) and re-run midcore gates run. For gate structure and ordering, see Gates reference and gates.yaml.
Agent not seeing files
The agent respects ignore files (e.g. .gitignore, .cursorignore) and scope locks. If a file is outside the allowed paths or ignored, it won’t be read or edited. Check your project’s ignore rules and scope settings. On Desktop or VS Code, ensure the workspace root is correct. See CLI / Terminal and VS Code extension.
CI
In CI, ensure the Midcore CLI is installed and midcore gates run (or your chosen command) runs in the project root with the same config as locally. Set any required environment variables in your CI platform. Exit codes: 0 = success, non-zero = failure; see CLI reference for exit codes and Environment variables for CI-friendly config. See also CI/CD.
Performance / slow runs
Agent or gates are slow on a large repo. Narrow scope (smaller task, specific files or directories), add or tighten ignore rules so fewer files are scanned, or run smaller tasks. For gates, ensure only the gates you need are enabled in gates.yaml.
Timeouts
Agent or gate times out. Increase time limits if your environment supports them (check Environment variables and Settings for timeout-related options). For gates, split heavy checks or optimize the underlying command.
Network / offline
I need to run offline or behind a proxy. The Desktop IDE and CLI support local (offline) LLMs; configure your local model in settings. For proxy or custom API URL, set the appropriate environment variables. See Environment variables and Desktop IDE.
Evidence or ledger issues
Where is evidence stored? How do I inspect it? Evidence is written under .maestro/evidence/ (or the path configured for your deployment). Entries are append-only. To inspect, read the ledger files or use any tool your deployment provides. See Gates & evidence and Gates reference.