> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usestatemachines.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Diagnose environment startup failures

> Read the resource state and failure before retrying creation, resume, or a wait.

When creation or resume fails, read the environment's current status and failure before trying another create call. An environment can exist even when the caller did not receive a successful response.

## Read startup failures

`EnvironmentFailedError` carries `error.environment`. Its `failure` identifies the app, code, and message when available. For `invalid_settings`, fix the named setting instead of retrying unchanged input.

If the environment never ran, State Machines deletes it with reason `failed`. If an environment previously ran and later fails to start or restart, it becomes `failed` and keeps its data for one day. A failed environment can be resumed, subject to the underlying failure and its remaining lifetime.

## Resolve creation errors

| Error | Next step |
| - | - |
| `version_unavailable` | Check the app ID and its available versions. The app needs a default version. |
| `environment_limit_reached` | Inspect starting and running environments. Pause or delete ones your task owns and no longer needs. |
| `invalid_request` | Read `fields` for the rejected input paths. |
| `invalid_status` | Read the resource's current status before choosing the next action. |
| `idempotency_key_reused` | The key was used with a different input. Replay the exact original input, or use a new key for a new environment. |
| `workspace_archived` | Use an active workspace for creation, or unarchive the original workspace. Existing environment lifecycle actions remain available. |

If the dashboard has no matching environments, clear its status and creator filters before deciding which resources need cleanup.

Read your applicable limits with `sm.me()`. Do not assume that another workspace or organization has the same allowance.

## Recover a timed-out wait

`WaitTimeoutError` means the SDK reached its wait deadline. It does not prove that startup failed, and it does not delete the environment. The error's `resource` is the last successful read, which can be null.

If you retained the environment ID, read it again and either wait for `running` or delete it. With `wait: false`, accept creation first, then call `wait` inside the `try` block whose `finally` deletes the environment.

If the create response itself was lost, replay the exact create input with the same idempotency key. Follow [operation recovery](/sdk-api/recovery) rather than generating a new key.

`UnexpectedStatusError` means the requested status requires another action. For example, waiting for a paused environment to become running does not resume it. Call `resume()` if the task still needs it, or delete it when finished.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.