Troubleshooting

A Local Mac job stays queued

Check these in order:

1. The selected installation is active and Local Mac routing is enabled.
2. The repository is private, still selected in GitHub, and enabled in Mirage.
3. At least one connected Mac targets this installation.
4. The Mac advertises the required profile and has a free slot.
5. The control plane is healthy; an outage cannot initiate fallback.

Fallback did not run

Confirm the workflow uses github.run_attempt. A literal runs-on: mirage-* label selects the same local scale set on every attempt and cannot reach a hosted runner.

runs-on: ${{ github.run_attempt == '1' && 'mirage-linux-x64' || 'ubuntu-24.04' }}

A job ran hosted unexpectedly

Open the run in Mirage and inspect the route reason. Common fail-closed causes are:

• installation or repository routing is disabled;
• the repository is public or visibility has not synced;
• the event comes from a fork or cannot be verified;
• all targeted Macs are full, paused, on battery, too hot, or stale; or
• a guest readiness or runner startup check failed.

A provider experiment is unavailable

Experiments revalidate the adapter fingerprint, immutable source SHA, installation, repository consent, permissions, provider profile, and backend health. An unavailable provider does not cancel other providers or change the source run.

Collect diagnostics

Start with the GitHub run and job links in Mirage. For local infrastructure details, open the menu-bar app's bounded redacted diagnostic log. It contains phases and stable error codes, not CI stdout or JIT credentials.