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. Use it (nomac attach), stop it, or start a second one with parallel: true.

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.