Troubleshoot a deployment

Diagnose setup, startup, worker, and resumability problems.

Start with the local prerequisite check, then inspect the affected Modal application:

uv run modal-devin doctor

Setup fails

The expected Modal Secret is missing

Create the Secret or pass its actual name to init --secret-name and doctor --secret-name. Its Devin credential must be authorized for the outpost.

The installed Modal SDK is unsupported

Install the Modal version supported by this modal-devin release, run uv sync, and repeat modal-devin doctor.

DEVIN_OUTPOSTS_TOKEN is missing

init creates a new outpost by calling the Devin Outposts API directly and currently needs a key from an admin-scoped Enterprise service user. Run uvx modal-devin init in an interactive terminal and enter that key when prompted.

The generated file already exists

Edit and redeploy the existing file, or choose another name or --outposts-dir. init never overwrites application code.

Image build failure

A build operation appears after prepare_image()

Move package installation, environment, copy, and clone operations before worker.prepare_image(base_image). Keep prepare_image() last.

A standard tool fails to install

Retry once to rule out a transient network failure, then inspect the Modal build output. Deployment can proceed after the failed dependency installs successfully.

No session starts

1. Confirm the session was assigned to the same outpost ID as the generated application.
2. Run modal-devin doctor with the Secret name used by the application; it checks that every outpost file in --outposts-dir has a matching deployed Modal app.
3. Confirm the deployed application’s scheduled function is active.
4. Inspect the scheduler logs for an authentication, API, image-build, or dispatch error.
5. Allow extra time for the first session while required images build.

An invocation may also exit quickly when another worker has already accepted the same session. This is normal; the winning worker continues uninterrupted.

A session invocation fails

WorkerExitedError

The Devin worker returned a nonzero status. Inspect the worker output immediately before the error for the actionable failure.

SessionStatusUnknownError

The runtime was unable to confirm a safe final state. It preserves the workspace when possible so a later attempt can recover. Check preceding API errors and retry the session after the upstream issue is resolved.

Startup readiness timed out

Inspect image availability and Sandbox startup errors. Increase readiness timing only when logs show a healthy startup consistently approaching the current limit.

Several sessions fail to start together

Inspect each reported error. Independent sessions that started successfully remain active; fix the shared credential, image, capacity, or API problem before retrying the failures.

Session resumption failure

If a stored filesystem snapshot expired or became unavailable, the next attempt starts from the current base image. Check snapshot retention and confirm that the deployment remained active while resumability was required.

For a legitimately large workspace that exceeds the configured preservation time, increase MODAL_DEVIN_SNAPSHOT_TIMEOUT_SECONDS or remove disposable caches and generated files.

If the problem appears to be a defect, open a GitHub issue without credentials or sensitive worker output. Report vulnerabilities privately through the repository’s security page.