Skip to content

Latest commit

 

History

History
189 lines (154 loc) · 26.7 KB

errors.mdx

File metadata and controls

189 lines (154 loc) · 26.7 KB
title Errors reference
description Every Simlock error code with its CLI exit code, its HTTP status, what it means and what to do about it.

A failed simlock command writes one line to stderr and exits with a non-zero code:

{"error":{"code":"RUNTIME_MISSING","message":"Runtime missing for ios 18.4"}}

The HTTP API answers with the same codes in the response body, with the status in the tables below:

{"error":{"code":"NO_CAPACITY","message":"No device capacity is currently available"}}

In a script, check code, not the message: the wording of a message can change, the code does not. For what a failing lease looks like from the agent's side, see When a lease fails.

Exit codes

Exit Error codes Meaning
0 — Success. For a simlock lease that stayed running: the lease ended because you asked.
1 INTERNAL, PROVISION_FAILED, UNKNOWN_LEASE, UNKNOWN_FILE, STDIN_FILE_FAILED, FILE_TOO_LARGE, LEASE_FILES_FULL, FILE_BUSY, UPLOAD_STALLED, BASELINE_SAVE_FAILED, FORBIDDEN, ADMIN_AUTHENTICATION_FAILED, SETUP_MCP_FAILED, DAEMON_STARTUP_FAILED, DAEMON_CONNECTION_LOST, DAEMON_STOPPING, DAEMON_UPDATING, HANDSHAKE_REQUIRED, PROTOCOL_VERSION_UNSUPPORTED, WORKER_UNREACHABLE, RELAY_TARGET_MISSING, ALERT_SEND_FAILED, UPDATE_RESOLVE_FAILED, HISTORY_UNAVAILABLE, DOCTOR_UNAVAILABLE, INPUT_UNAVAILABLE, NUKE_UNAVAILABLE, UNKNOWN_DAEMON_ERROR, SERVICE_FAILED, CANCELLED, TUNNEL_UNSUPPORTED, TUNNEL_PORT_IN_USE, TUNNEL_BAD_PORT, TUNNEL_LIMIT, TUNNEL_FAILED, TUNNEL_UNAVAILABLE, TUNNEL_DISCONNECTED, TUNNEL_CALLER_PORT_IN_USE The command failed. Read the code and the message.
2 USAGE, BAD_REQUEST, BASELINE_MISMATCH, BAD_FRAME, UNKNOWN_REQUEST, IDEMPOTENCY_CONFLICT, PASSTHROUGH_REFUSED, UNKNOWN_PASSTHROUGH_TOOL, SETUP_REFUSED, GATEWAY_NOT_PRESENT, UPDATE_UNSUPPORTED_INSTALL, UPDATE_SHARED_INSTALL, UNSUPPORTED_IN_GATEWAY_MODE, UNSUPPORTED_IN_WORKER_MODE, WORKER_CONNECTED, WORKER_NOT_CONNECTED The request was wrong. Running it again unchanged fails again.
10 QUEUE_TIMEOUT, EXEC_TIMEOUT, DOWNLOAD_TIMEOUT A deadline ran out.
11 NO_CAPACITY, DEVICE_BUSY, COMPONENT_BUSY Busy right now. The same request can pass later.
12 NO_DRIVER, CAPABILITY_MISSING, RUNTIME_MISSING, UNKNOWN_MODEL, ROTATION_UNSUPPORTED, INSUFFICIENT_DISK_SPACE, LICENSE_NOT_ACCEPTED, DOWNLOADS_DISABLED, COMPONENT_NOT_OWNED, COMPONENT_IN_USE, UNKNOWN_BASELINE, BASELINE_STALE, BASELINE_IN_USE, DEVICE_NOT_ENROLLABLE, UNKNOWN_DEVICE, HISTORY_NOT_KEPT, UNKNOWN_WORKER, UNKNOWN_ALERT_DESTINATION What you named does not exist here, or this machine cannot provide it.
13 REQUESTER_ALREADY_LEASED, LEASE_ID_TAKEN, LEASE_ENDED The request clashes with a lease or request that exists or recently ended.
14 TUNNEL_LEASE_ENDED simlock lease without --detach: the daemon ended the lease before you did (expiry, an operator's release, or a device that could not be recovered). The lease-lost line on stderr gives the reason.
15 — simlock component install with --worker or --all-workers: at least one worker did not end installed or already-installed. The result on stdout says which.
16 ADMISSION_DENIED, ADMISSION_FAILED The gateway's admission policy refused the request, or could not decide.

simlock simctl and simlock adb exit with the wrapped tool's own exit code, which can be any of these numbers. For those two commands, look for the {"error":...} line on stderr, which only Simlock writes.

Leasing a device

Code Exit HTTP Meaning What to do
NO_CAPACITY 11 503 No device can start now, and the request was told not to wait (--no-wait). Through a gateway: no worker that takes requests can serve it. Try again later, or drop --no-wait to queue. Over HTTP the answer carries Retry-After: 5. The details name a capacityReason: device-limit, ram-budget, memory-pressure, global-running-limit or platform-running-limit.
DAEMON_UPDATING 1 503 The daemon is updating (simlock update) and takes no new leases. A request that was waiting when the update began gets it too. A lease you already hold renews and releases as usual. Run the command again once the daemon is back, or lease from another worker.
QUEUE_TIMEOUT 10 500 The request waited in the queue for its whole --timeout and got no device. Raise --timeout, or check simlock list --requests for why requests wait.
REQUESTER_ALREADY_LEASED 13 409 Your requester identity already holds or waits for its limit of leases (lease.maxPerRequester, 1 by default, counted per platform when the operator sets a limit for each), or, with a limit per platform, has a request waiting on that platform. The message names your lease. Release that lease first, or give each agent session its own identity.
LEASE_ID_TAKEN 13 409 --lease-id names an ID that an active lease or a waiting request already holds. Use a new ID. Never reuse a lease ID.
LEASE_ENDED 13 409 --lease-id names an ID whose lease ended within the last lease.endedIdRetentionMs (24 hours by default). The message and details give when it ended. The gateway or worker that held the lease keeps the ID across its own restarts. Use a new ID. A retry of a request whose lease already ended must not be sent again under the same ID.
ADMISSION_DENIED 16 403 The gateway's admission command refused the request. The message ends with the command's reason, and the details carry it as reason. Read the reason: it is the operator's policy. Ask the operator, or change what the request names.
ADMISSION_FAILED 16 503 The gateway's admission command could not decide: it exited non-zero, ran past gateway.admission.timeoutMs, printed more than 64 KiB or something that is not an answer, was killed, or could not start. The gateway refuses rather than let the request through. The message and the details (cause) say which. Tell the operator: the gateway log names the cause and the command's stderr. The same request can pass once the command is fixed.
IDEMPOTENCY_CONFLICT 2 409 A lease request reused an idempotency key its requester already sent for a different device, except list or lease ID. Send a new key for a new request.
PROVISION_FAILED 1 500 Creating or booting a device for the request failed. A device that fails to boot, by timing out or by crashing, fails the request at once, unless the request has --except. Any other failure is tried again once, and a request with --except counts a failed boot of a device it was given, warm or new, the same way. The message carries the platform tool's error. Read the message and simlock daemon logs, then run simlock doctor.
UNKNOWN_MODEL 12 422 The model is not one this platform offers here, no model of the requested class exists, or the worker serves only enrolled devices of the platform (<platform>.virtualDevices is false) and the request did not ask for a physical one. Run simlock catalog for the models and their exact names. When the message names <platform>.virtualDevices, ask for a physical device: --physical, or physical: true over MCP and HTTP.
RUNTIME_MISSING 12 422 The OS version, or an image of the --image-tag, is not installed. A range or an image tag never downloads. Add --allow-download, install it with simlock component install, or pick an installed version from simlock catalog.
NO_DRIVER 12 422 This machine cannot run the platform: iOS on Linux, or a platform whose tools are missing. Run simlock doctor to see what is missing, install it, then restart the daemon.
CAPABILITY_MISSING 12 422 No worker that could serve the request has every optional module it asks for, such as screen streaming. Only the programmatic client asks for modules. Ask for fewer, or turn the module on for a worker under capabilities in its configuration.
UNKNOWN_LEASE 1 404 No active lease has this ID: it was released, it expired, or it never existed. Take a new lease.
BAD_REQUEST 2 400 The request has an invalid value: an unknown class or mode, both --device and --class, a TTL over lease.maxTtlMs, --image-tag on iOS, --physical with --mode, --except on a lease that is not a slim iOS simulator or naming a category twice, one the worker does not slim or a bad name, and so on. The message names the field. Fix the value the message names.
CANCELLED 1 499 The programmatic client gave up a lease request it was waiting on. Never sent by the daemon. Nothing, unless you did not mean to cancel.

Runtimes, images and downloads

Code Exit HTTP Meaning What to do
DOWNLOAD_TIMEOUT 10 504 An install ran longer than downloads.timeoutMs (20 minutes by default), counting the time it waited behind another download on the same platform. Run it again, or raise downloads.timeoutMs.
DOWNLOADS_DISABLED 12 403 downloads.policy is never, so no install starts. Change downloads.policy, or install the component by hand.
INSUFFICIENT_DISK_SPACE 12 422 The component does not fit in the free disk space. The message gives the bytes needed and available. Free disk space, or remove components with simlock component remove.
LICENSE_NOT_ACCEPTED 12 422 An Android SDK licence must be accepted before the install. downloads.acceptAndroidLicenses is false by default. Accept the licences with sdkmanager --licenses, or set downloads.acceptAndroidLicenses to true.
COMPONENT_NOT_OWNED 12 409 component remove of a component Simlock did not install, or one that changed on disk since. Remove it with the platform's own tools if you mean to.
COMPONENT_IN_USE 12 409 component remove of a component a device still uses, Simlock's or one of yours. Delete those devices first.
BASELINE_SAVE_FAILED 1 500 baseline save ended the lease, but Simlock could not keep a copy of the device. The message gives the reason. No baseline was saved, and the device is set aside for cleanup. Lease a fresh device, prepare it again and save again.
UNKNOWN_BASELINE 12 404 baseline remove, or a lease request with --baseline, naming a baseline this worker does not have. Through a gateway: no worker holds the baseline, or the worker --worker names does not. List the baselines with simlock baseline list.
BASELINE_MISMATCH 2 422 A lease request names a baseline and also a platform, model, OS, mode or image tag that differs from it. The message names the first field that differs. Drop the field, or change it to the baseline's own value.
BASELINE_STALE 12 422 A lease request names a baseline whose runtime or image has been removed since it was saved, or an iOS baseline saved before simulators stopped sharing folders, or from a lease made before that. The message gives the reason. Install the runtime or image again, or save the baseline again from a new device.
BASELINE_IN_USE 12 409 baseline remove of a baseline a lease still uses. The message names the lease. End that lease, or remove the baseline after it.
COMPONENT_BUSY 11 409 component remove while an install or removal runs or waits on that platform. Try again once it ends.

Physical devices

Code Exit HTTP Meaning What to do
DEVICE_NOT_ENROLLABLE 12 422 device add of a device that cannot be enrolled. The reason is one of: not connected, network only, not trusted, Developer Mode off, OS too old, unsupported kind, locked, unreadable, a simulator or emulator, enrolled on the other platform, or enrolled under another ID. Fix what the message names (connect it by USB, trust this computer, turn on Developer Mode, unlock it) and run device add again. For a phone enrolled under another ID, run device remove on the record the message names first.
DEVICE_BUSY 11 409 device add or device remove of a device that is leased, being cleaned, or held by another operation. baseline remove of a baseline whose copy is being cleaned up or held by another operation (a leased copy gets BASELINE_IN_USE). Try again once that ends.
UNKNOWN_DEVICE 12 404 device remove of an ID that is not an enrolled device. Check the ID with simlock list --devices.

Tunnels

A lease's tunnel socket (GET /v1/leases/{id}/tunnel, on a worker with capabilities.tunnel.enabled) refuses a HELLO in a REFUSED frame and closes with 4003, with TUNNEL_UNSUPPORTED, TUNNEL_PORT_IN_USE, TUNNEL_BAD_PORT, TUNNEL_LIMIT or TUNNEL_FAILED. TUNNEL_UNAVAILABLE, TUNNEL_DISCONNECTED, TUNNEL_CALLER_PORT_IN_USE and TUNNEL_LEASE_ENDED are not sent by a worker's tunnel socket; the rows below say who raises them.

Code Exit HTTP Meaning What to do
TUNNEL_UNSUPPORTED 1 422 The lease is on an iPhone, which takes no tunnels; or an emulator adb tunnel was asked for on a lease that is not on an Android emulator (emulator adb: the lease is on an Android phone; emulator ports need an Android emulator, and the same for an iOS simulator or an iPhone). Use an Android emulator or phone, or an iOS simulator; for emulator adb, an Android emulator.
TUNNEL_PORT_IN_USE 1 409 The device port is already taken: by another reverse rule on an Android device, for example one you added with simlock adb reverse, or, on an iOS simulator, by any process on the worker that listens on that port, another lease's reverse included. Remove that rule first, or use another port.
TUNNEL_BAD_PORT 1 422 A device port is an integer outside 1024 to 65535. A port that is not an integer at all is refused BAD_REQUEST. Name a port in that range.
TUNNEL_LIMIT 1 409 The lease would have more than 8 tunnels across its sockets. Close a tunnel first.
TUNNEL_FAILED 1 502 adb could not set the tunnel up, or the worker ran out of ports for tunnels. The message carries adb's own words. Read the message, then try again.
TUNNEL_UNAVAILABLE 1 503 Through a gateway: the worker that holds the lease has tunnels off. Turn on capabilities.tunnel.enabled on the worker.
TUNNEL_DISCONNECTED 1 503 simlock tunnel lost its connection to the worker or gateway. Open the tunnel again.
TUNNEL_CALLER_PORT_IN_USE 1 409 The caller port a forward or emulator adb tunnel listens on is in use on your machine. Pick another caller port.
TUNNEL_LEASE_ENDED 14 410 The lease ended while the tunnel was open. Take a new lease.

Running commands on a device

Code Exit HTTP Meaning What to do
PASSTHROUGH_REFUSED 2 422 Simlock refuses this simctl, adb or devicectl command: a verb that creates, erases or deletes devices or touches every device at once (such as simctl erase or adb kill-server), a flag that points the tool at another device set or adb server, simctl on a physical device, simctl or adb on a lease of the other platform, a device.exec command that names a device other than the lease's (booted, another UDID, adb -s with another serial, -e, -d, -t, a different devicectl --device), or adb shell with no command where there is no terminal. simlock simctl and simlock adb report a refusal as USAGE (exit 2), not as this code. Drop the refused flag or verb, leave the device out of the command, or name the command to run. The message says which.
UNKNOWN_PASSTHROUGH_TOOL 2 422 A command for a tool Simlock does not run on devices. Use simctl or adb.
EXEC_TIMEOUT 10 504 A command run on a device through a gateway ran longer than exec.timeoutMs (10 minutes by default) and was stopped. Split the work, or raise exec.timeoutMs on the worker.
ROTATION_UNSUPPORTED 12 422 The lease is not on an iOS phone or tablet simulator, so POST /v1/leases/{id}/rotate has nothing to turn. The message names what it is on: an Apple TV, Apple Watch or Apple Vision simulator, another iOS model, an Android emulator or phone or tablet, an iPhone or an iPad. Rotate a lease on an iPhone or iPad simulator.
INPUT_UNAVAILABLE 1 503 The lease's simulator cannot take input right now: for a rotate, the part of Simlock that sends input to it did not start within 10 seconds or failed, and the message ends with the reason. Through a gateway, the same code answers an input socket when the lease's worker has input off. Run it again. If it repeats, check simlock daemon logs.

Lease files

Code Exit HTTP Meaning What to do
FILE_TOO_LARGE 1 413 An upload to a lease is over 2 GiB: its Content-Length, or the bytes received when it has none. Nothing is stored. Send a smaller file.
LEASE_FILES_FULL 1 413 The upload would take the lease's folder past 4 GiB, counting every file in it and the uploads running at the same time. The message gives the bytes held. Delete files with DELETE /v1/leases/{id}/files/{name}, or finish the other uploads first.
UNKNOWN_FILE 1 404 The lease has no file with this name (names match ignoring case). List the files with GET /v1/leases/{id}/files.
FILE_BUSY 1 409 Another request is uploading a file with this name. Wait for it to finish, then upload again.
STDIN_FILE_FAILED 1 500 The stored file named by stdinFile could not be read to its end, so the command was stopped. The stream ends with this error. Run the command again. Upload the file again if it keeps failing.
UPLOAD_STALLED 1 408 No byte of the upload's body arrived for 330 seconds. The previous file is kept. Send the upload again from the start.

A bad file name is BAD_REQUEST, and a worker whose free disk is under diskPressure.freeBytesThreshold answers an upload with INSUFFICIENT_DISK_SPACE.

Daemon and connection

Code Exit HTTP Meaning What to do
DAEMON_STARTUP_FAILED 1 503 The CLI started the daemon, and the daemon exited, dropped the connection or did not answer within 20 seconds. Also when it was still starting 90 seconds after it answered; it is then left running. The message carries the daemon's own start error. Read the message and simlock daemon logs, fix the cause, and run the command again.
DAEMON_CONNECTION_LOST 1 503 The connection to the daemon dropped mid-command. A lease held by simlock lease is not released and stays yours until its deadline. Start the daemon again; renew the lease with simlock lease renew <lease-id> or let it expire.
DAEMON_STOPPING 1 503 The daemon is shutting down, or stopped while an install was running. Run the command again once the daemon is back.
PROTOCOL_VERSION_UNSUPPORTED 1 400 The CLI and the running daemon are different Simlock versions that cannot talk to each other. Restart the daemon after an upgrade: simlock daemon stop, then any command.
UNKNOWN_REQUEST 2 400 The daemon does not know this operation, usually because it is older than the CLI. Restart the daemon so it runs the installed version.
BAD_FRAME 2 400 The daemon could not read a message a client sent it. Only a client you wrote yourself causes this; fix the client.
HANDSHAKE_REQUIRED 1 400 A client sent a request before it said hello to the daemon. Only a client you wrote yourself causes this; fix the client.
UNKNOWN_DAEMON_ERROR 1 500 The daemon answered with a code this client does not know, usually because the daemon is newer. The message is the daemon's. Upgrade the client to the daemon's version.
INTERNAL 1 500 Something unexpected failed. Check simlock daemon logs. If it repeats, report it with the log.
DOCTOR_UNAVAILABLE 1 503 This daemon cannot run doctor. A daemon started by simlock always can. Check simlock daemon logs, and report it if it repeats.
NUKE_UNAVAILABLE 1 503 This daemon cannot run nuke. A daemon started by simlock always can. Check simlock daemon logs, and report it if it repeats.

Updating Simlock

Code Exit HTTP Meaning What to do
UPDATE_RESOLVE_FAILED 1 502 npm could not find the version (No match found for version 9.9.9) or could not be reached. The message carries npm's own text. Nothing changed. Check the version with npm view simlock versions, or npm's registry and network settings on that machine.
UPDATE_UNSUPPORTED_INSTALL 2 409 Simlock was not installed with npm i -g simlock (a source checkout, a pnpm global). The message names where it runs from. Nothing changed. Update it the way you installed it.
UPDATE_SHARED_INSTALL 2 409 The worker and the gateway of this user share one install, and the other one is running. Nothing changed. Stop the other daemon (simlock daemon stop, or simlock --gateway daemon stop), update, then start it again.

Access

Code Exit HTTP Meaning What to do
FORBIDDEN 1 403 Your role may not do this, or the lease belongs to a different requester. The CLI falls back to the agent role when it has no working admin credential. Pass --token or set SIMLOCK_ADMIN_TOKEN, or run the command on the daemon's machine as the user who runs it.
ADMIN_AUTHENTICATION_FAILED 1 401 The admin credential was rejected. The CLI does not stop on it: it connects as an agent and writes a notice. Check the token, or create a new one with simlock token create.

Gateway and workers

Code Exit HTTP Meaning What to do
GATEWAY_NOT_PRESENT 2 404 --gateway on a machine with no gateway. Raised by the CLI and MCP server before they connect, never over HTTP. Start one with simlock --gateway daemon start, or drop --gateway.
UNSUPPORTED_IN_GATEWAY_MODE 2 501 The command acts on one machine's devices or components (doctor, cleanup, nuke, warm, device, component list, component remove, component install without a worker flag), and the daemon that answered is a gateway. Run it against the worker, with --local on that machine. For component install, name workers with --worker or --all-workers.
UNSUPPORTED_IN_WORKER_MODE 2 501 The command acts on a gateway's workers or alerts (worker drain, undrain, remove, update, alerts test, component install --worker), and the daemon that answered is a worker. Run it against the gateway, with --gateway on that machine.
WORKER_NOT_CONNECTED 2 409 worker update named a worker the gateway knows but has no open connection to: worker <id> is not connected. It is also the answer when the worker does not reply within 90 seconds: worker <id> did not answer within 90 s; check simlock worker list. In that case the update may still have started. Check the worker with simlock worker list. Run the update again once it is connected.
UNKNOWN_WORKER 12 404 The gateway has no worker with this ID. Check the ID with simlock worker list.
WORKER_CONNECTED 2 409 worker remove of a worker that is still connected. Drain it, stop it or let it disconnect, then remove it.
WORKER_UNREACHABLE 1 503 The worker that holds this lease or would serve this request is not connected to the gateway, or, in the first minute after the gateway starts, has not yet reported its leases. Check the worker is running and can reach the gateway.
RELAY_TARGET_MISSING 1 503 The gateway asked a worker for an optional module, such as the screen stream or agent-device, that the worker does not run. Turn the feature on for that worker, or upgrade it to the gateway's version.
UNKNOWN_ALERT_DESTINATION 12 404 alerts test names a destination the gateway's configuration does not list, or the gateway has none. Check the names under the gateway's alert configuration.
ALERT_SEND_FAILED 1 502 The alert receiver answered with a status that is not 2xx, could not be reached, or did not answer in time. The message says which. Check the destination's URL and the receiver.

Usage history

Code Exit HTTP Meaning What to do
HISTORY_NOT_KEPT 12 422 stats for a window that ends before the oldest figure the history holds. The message says when the figures start. Ask for a later window.
HISTORY_UNAVAILABLE 1 503 The history file (history.db) could not be opened, so no usage figures or past events can be read. Check simlock daemon logs for why.

Codes outside this table

The CLI and the HTTP API each add a few codes of their own:

Code Where Exit or HTTP Meaning What to do
USAGE CLI exit 2 A bad flag, a missing argument or an unknown command. Also a config.json the CLI rejects before it starts the daemon, and a SIMLOCK_HOME too long for the daemon's socket path. Run the command with --help.
SETUP_REFUSED CLI exit 2 simlock setup found a file or a symlink where its simlock skill directory goes. Nothing was written. Move it aside and run setup again.
SETUP_MCP_FAILED CLI exit 1 simlock setup wrote the skills, but a tool's mcp add command failed or ran longer than 30 seconds. The message names each tool and the reason. Run the tool's mcp add command by hand, as the message and Connect your agent show.
SERVICE_FAILED CLI exit 1 simlock daemon install, uninstall or daemon stop, or a start through the service, could not finish: the service manager (launchd or systemd) failed or did not answer in time, or the old daemon did not stop. The message names the command and its first error line. Fix what the message names and run the command again.
UNAUTHENTICATED HTTP 401 The request has no token, or one the daemon does not accept. Send a valid token as Authorization: Bearer <token>.
UNSUPPORTED_MEDIA_TYPE HTTP 415 A request with a JSON body did not send Content-Type: application/json. Send the header Content-Type: application/json.
UNKNOWN_LEASE_REQUEST HTTP 404 No lease request has this ID. Check the ID the create call returned.
REQUEST_NOT_CANCELLABLE HTTP 409 The lease request was already granted, or device work for it is under way. When it was granted, the answer carries the leaseId. Release the lease in place of cancelling the request.