Skip to documentation
MMirageDocs

Reference

Troubleshooting

Fix setup problems, unavailable machines, queued jobs, and unexpected fallback runs.

My repository is missing or cannot be enabled

  1. Select the repository’s GitHub account in Mirage’s account menu.
  2. In Settings, use Manage access on GitHub and confirm the repository is selected for the Mirage App.
  3. Return to Mirage and select Sync repositories or Sync repository details.
  4. Confirm it is a private, unarchived repository. Public repositories cannot use Mirage execution.
  5. For local-infrastructure routing, enable both Allow opted-in repositories and the repository’s Local infrastructure switch. Use Retry provisioning if setup reports an error.

If you cannot change these settings, ask an account owner or admin to check your Mirage role and GitHub App permissions.

My Mac is connected but not ready

Open the Mac in Machines and check the individual runner profile. A connection means Mirage can reach the host; it does not mean every runner environment is ready.

What to checkWhat to do
Image download or preparationWait for preparation and its self-test. If it fails, read the profile’s error and Next step.
Insufficient disk or memoryFree space or reduce the configured runner resources. Image preparation needs room beyond the job’s writable disk budget.
Paused, on battery, or under loadResume the host, connect power, and allow resource pressure to settle.
Linux x64 unavailableCheck that Rosetta is installed and the x64 self-test passes.
macOS unavailableCheck that the profile is enabled, its image is prepared, and the required desktop session and GUI bridge are configured.
Offline after rebootCheck the network and power. FileVault may need a person to unlock the disk; native macOS jobs also need a desktop login.

Use mirage host doctor on the Mac for the detailed checks. See Use the CLI if the command is not found.

My job stays queued

  1. Confirm the account and repository settings above are enabled and provisioning finished.
  2. Compare the workflow’s runs-on label with the supported runner labels.
  3. Check Runners for a machine available to the selected account. Confirm the required profile is Ready and has a free slot.
  4. Check the machine’s Available to list and any capacity grant needed by the account.
  5. Check GitHub for an Actions outage and confirm Mirage’s dashboard is reachable.

If you need to unblock CI while Mirage is unavailable, restore the job’s original GitHub-hosted label and push the workflow. For a workflow already using the attempt expression, cancelling and manually rerunning it in GitHub selects the hosted label on the next attempt. Check for side effects before rerunning a workflow.

My job ran on GitHub instead of my Mac

Open the job in Mirage and inspect its route reason and attempt number. Common causes are:

  • No eligible slot: the Mac was busy, paused, asleep, on battery, or short of resources.
  • The required runner profile was not ready or startup failed.
  • The account or repository disabled local execution, or the event was not eligible.
  • The workflow was manually rerun and its attempt expression selected GitHub.

Fix the reported cause and trigger a new workflow run to try local execution again. Re-running an existing run keeps its later attempt number and will still select the hosted fallback with the documented expression.

Fallback did not run

Check for a literal runs-on: mirage-* label. A literal label targets Mirage on every attempt. For hosted fallback, use the full expression:

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

Automatic fallback also requires the GitHub App to retain access and Mirage to be reachable to request the rerun. Direct Cloudflare jobs do not have automatic fallback. A normal failed test does not trigger fallback either; inspect its logs in GitHub.

Cloudflare or a provider comparison is unavailable

For Cloudflare, check that the repository’s Cloudflare switch is on and the selected Shared or BYO backend is ready. Shared mode needs access enabled by Mirage; BYO setup failures show an error in Settings. Docker-dependent jobs need a different provider.

For comparisons, confirm the onboarding PR is merged and the job’s configuration is applied. Refresh job discovery if the workflow changed, approve any requested GitHub App permissions, and read the provider’s unavailable reason. Only eligible completed jobs can start an experiment. See Compare CI providers for the supported workflow shapes.

Collect diagnostics

Record the GitHub run and job links, repository and account, attempt number, runner label, and Mirage’s route reason. For a host problem, include the machine’s Mirage version and the affected profile’s readiness message.

On the affected Mac · requires the Mirage CLI
mirage host status
mirage host doctor
mirage host diagnostics --lines 80

Share those details with the person administering Mirage for your team when asking for help. For a test failure, include the relevant GitHub step output. Review any diagnostics before sharing them, and leave out secrets, tokens, and pairing codes.