Troubleshoot a desktop

Diagnose readiness, X11 input, screenshots, adapters, storage, and warm capacity.

The daemon is alive but not ready

/healthz checks the daemon process. /readyz also checks Xvfb, the input backend, the window manager, screenshots, and noVNC when enabled.

Read the per-check failure list from /readyz. Modal’s TCP probe can pass before desktop readiness passes.

Use computer.processes.logs("xvfb") when Xvfb fails. Confirm that DISPLAY matches the configured display. The default is :99.

If the error names placement, compare the requested Function selector, observed Function region, and target region. Both resources must declare the same supported selector. Public narrow selectors such as us-west can produce provider-native runtime values such as us-west-2, us-west1, or westus3. A granted granular selector such as us-west-2 requires an exact match.

If the error names computer-step-envelope-v1, install a daemon that supports the Step protocol. Keep the failed operation stopped until the compatibility check passes.

A screenshot is black or empty

Wait for /readyz. Confirm that the target application has a mapped window.

Use computer.windows.wait_for(...) after you launch an application. An immediate screenshot can arrive before the window manager draws the first frame.

X11-SHM fails readiness

MSS is the default. Choose X11-SHM only when the managed Image contains the native extension and worker. Confirm that Xvfb uses 24-bit TrueColor and that the native module imports inside the Sandbox.

auto can use MSS after an ordinary native failure. Explicit x11-shm fails closed when its source is unavailable. A display reply timeout also fails closed because MSS and file-capture tools depend on the same unresponsive display.

A display restart closes generation-bound X11 clients before it relaunches dependents and proves readiness. Keep the source opt-in after recovery.

Keyboard input does not appear

Activate the target window before you send input. Confirm that the daemon uses the intended DISPLAY.

Set COMPUTER_USE_INPUT_BACKEND=xtest to test the native path. Set it to xdotool to test the compatibility path.

For Unicode text, use method="auto". The daemon uses native keystrokes when the active layout can represent the text. It uses clipboard paste for long or unmapped text and then restores the prior clipboard.

Do not replay an input action after input_may_be_partial. The first attempt might have changed the desktop.

Identify the active backend

Read these response headers for one successful direct request:

Header	Operation
X-Computer-Use-Input-Backend	Mouse or keyboard input.
X-Computer-Use-Window-Backend	Window control.
X-Computer-Use-Capture-Backend	Raw screenshot capture.

Use /v1/capabilities for process configuration and readiness. Use per-response headers to attribute concurrent requests.

Provider actions click the wrong place

The provider image and desktop use different coordinate spaces. Pass CoordinateSpace to the adapter. Use the dimensions of the exact screenshot that you sent to the model.

A recording is empty or damaged

Stop the recording with computer.recordings.stop(...) before you terminate the Sandbox. This lets ffmpeg write its trailer.

Inspect the sanitized Recording.error value when stop fails.

Persisted artifacts are missing

Ephemeral artifacts disappear when the Sandbox ends.

For Modal Volume v2, mount the Volume over the artifact path. Set StorageConfig(persist_artifacts=True). Call computer.artifacts.sync() before termination.

Reload an already-mounted reader before you check for committed data. Use a run-specific path. Do not let two writers replace the same file.

Immediate sync requires Modal Volume v2.

Browser prewarm did not help

Confirm that /v1/capabilities reports browser or browser-gpu as the image profile. Prewarm moves browser startup into desktop startup. Page network, authentication, and rendering time remain in the first navigation.

For GPU tests, read /v1/browser/status. A Modal GPU allocation alone does not prove hardware browser rendering.

A warm-pool candidate expired

Set min_remaining_seconds to cover the expected task. The claim path rejects a candidate without enough lifetime.

Always check /readyz after attach. A listed Sandbox can be stopping or recovering.

A filesystem snapshot lacks GUI state

Use directory snapshots for files and installed application state. Do not use them to preserve live windows, process memory, or an authenticated browser session.

Create a normal computer-use Sandbox. Mount the snapshot image into the required path. Start the applications again. Verify readiness.

A noVNC URL was shared

Treat the URL as compromised. Terminate the Sandbox immediately. Create a new Sandbox to receive a new tunnel and generated password.