Troubleshooting

Check the runtime first

.\scripts\maestro-runtime.ps1 status
maestro.cmd status
maestro.cmd doctor <project-key>
Invoke-WebRequest http://127.0.0.1:4787/api/health

If the API is not healthy, restart the runtime and inspect .maestro/runtime/ logs. A CLI command that calls the Dashboard API cannot work while the service is stopped.

Provider not detected

Install the provider CLI using its official instructions, complete login in the provider’s own terminal/browser flow, then use Providers → Rescan. Restarting is normally unnecessary. Check that the Maestro process sees the same PATH as your terminal. “CLI installed” and “authenticated” are separate states.

Antigravity

The agy binary must be available and the local Antigravity session must be active. A visible agy prompt is not sufficient for every quota RPC. Re-run the provider’s official login/session flow, then rescan. If the provider denies a command because of its permission policy, inspect that policy rather than interpreting the message as a Maestro network failure.

Task will not start

Confirm the project is Git-backed, clean, prepared and has at least one provider capable of the requested phase. Run Environment Doctor. Missing project node_modules may prevent deterministic validation, but the runtime distinguishes validation-only gaps from hard Git/runtime blockers.

Blank, stale or broken UI

Check http://127.0.0.1:4787/api/health, refresh the browser, and verify the UI dev server is on 4788. In a source checkout rebuild the UI with npm run build:ui. In the packaged app, reinstall the current version if its compiled UI is missing; do not copy a developer .env.local into the installer directory.

PR link opens inside the app

Use the public URL shown in the review item or copy it into an external browser. GitHub CLI authentication and the browser are separate from the local Dashboard.