Troubleshooting

The errors agents meet most often, what each means, and what to do.

Errors

• insufficient_credit
  The account has too little credit. Your agent gets a payment link with get_mac_checkout, hands it to you, then retries with the same request_key.

• session_limit_reached
  A Mac is already running, and the answer names it, who started it (with this API key or another) and its last command. Use it if it is yours (nomac attach), start a second one with parallel: true, or wait in line for it with queue_seconds (nomac start --queue 1800).

• confirm_required
  Another API key sent this Mac a command or opened SSH to it in the last 5 minutes: another agent may be working on it. Stop it with confirm: true (nomac stop --confirm) only if it is yours and finished.

• queue_expired
  The start waited in line as long as queue_seconds said, and the account's other Macs (or its drive's) were still running. Nothing was charged. Use one of them, or start again with a longer wait.

• queue_full
  The account already has 5 starts waiting in line. Follow one of them, or stop one you no longer need, then start again.

• drive_in_use
  The drive the start named is on a Mac that is starting or running, and the answer names it. Use it (nomac attach), start with reuse: true (--reuse), or name another drive.

• drive_limit_reached
  The account keeps at most its limit of drives (10 by default), and none can make room: the default is never replaced, and every other one is on a Mac or still saving. Use one of them, or empty one (nomac drive reset NAME).

• session_id_required, no_mac_running
  Two Macs run and the call did not say which, or none runs. Name the session, or start one.

• output_expired
  An old command's log is gone, but its exit code is kept. Do not run the command again to read it.

• stop_notice
  The Mac stops within 15 minutes, at its time limit, its spend cap or the end of the credit. extend_mac adds time; save work to ~/drive.

Situations

• A command is still running (CLI exit code 75)
  It keeps running on the Mac. Wait for it with get_mac_job or nomac job ID --wait 600, and never run it again.

• An answer was lost
  Repeat the call with the same request_key and arguments: you get the same Mac or job back, never a second one.

• The Mac stopped during a background build
  The idle timeout counts commands, SSH and the desktop, not leftover processes. For unattended work, raise idle_timeout_seconds, up to 3600.

• The CLI cannot reach NoMac from a sandbox
  Allow nomac.app, *.nomac.app and *.r2.cloudflarestorage.com in the sandbox's network settings.

Still stuck

Your agent files it with report_issue, with the session's ID and the command's job ID. NoMac attaches the session's context and answers in the same ticket; report_issue with no description reads the reply. You can also contact us or check the status page.