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

# Errors

> What a failure looks like on each surface, from a file call's POSIX condition to a shell line's exit status.

Mirage names a failure once and each surface reports it in its own form. A file
call fails with a POSIX condition, a shell line ends with an exit status and a
GNU-worded line on stderr, and HTTP, RPC, MCP and the kernel mounts carry one of
those two.

## File calls

A file call (`read`, `write`, `stat`, `readdir`, `rename`, ...) names its
failure with one of these conditions, whatever the backend. A service's own
error becomes the condition it means, such as an object that is not there
becoming `ENOENT`. One that means none keeps its own words in an exception
and in a shell diagnostic. HTTP answers it `500`, and RPC `-32603`, with
`detail` set to `internal server error` and no `errno`, since those words can
carry credentials or host paths; they stay in the server's logs.

| Condition | Message | HTTP | Means |
| - | - | - | - |
| `ENOENT` | No such file or directory | `404` | The path is not there, or no mount owns it. |
| `ENOTDIR` | Not a directory | `400` | A component of the path is a file. |
| `EISDIR` | Is a directory | `400` | The call needs a file. |
| `EEXIST` | File exists | `409` | The name is taken. |
| `ENOTEMPTY` | Directory not empty | `409` | `rmdir` on a directory with entries. |
| `EACCES` | Permission denied | `403` | A policy refused the call, or the service denied access. |
| `EPERM` | Operation not permitted | `403` | The call is not allowed on this entry. |
| `EROFS` | Read-only file system | `403` | The mount's mode stops below write. |
| `EXDEV` | Invalid cross-device link | `400` | A rename across two mounts. |
| `ENOTSUP` | Operation not supported | `400` | The backend does not offer the call. |
| `ELOOP` | Too many levels of symbolic links | `400` | A link loop stands in the path. |
| `EINVAL` | Invalid argument | `400` | The call's arguments are invalid. |
| `EBUSY` | Device or resource busy | `409` | A mount root, or the workspace is busy. |
| `EFBIG` | File too large | `500` | A read the backend will not serve whole. |
| `EDQUOT` | Disk quota exceeded | `507` | A write past the mount's capacity. |
| `EPIPE` | Broken pipe | `500` | A write to a closed pipe. |
| `EIO` | Input/output error | `500` | The backend failed. |
| `EBADF` | Bad file descriptor | `500` | A read from a closed or write-only descriptor. |
| `NO_XATTR` | No data available | `404` | The attribute is not set. Python on macOS says `Attribute not found`. |
| `STALE_WRITE` | changed since it was read; read it again before writing | `500` | A [conditional write](https://docs.mirage.strukto.ai/home/configuration.md#read-and-write-policies) lost its condition. |

Each surface carries the condition its own way:

| Surface | Form |
| - | - |
| Python | An `OSError` with `errno` set, raised as the builtin class for it (`FileNotFoundError`, `PermissionError`, ...). A path no mount owns raises `NoMountError`, a `ValueError`. `mirage.errors.classify(exc)` names the condition for either. |
| TypeScript | An `Error` whose `code` is the condition's name (`ENODATA` for `NO_XATTR`), as Node's `fs` does. A path no mount owns sets `noMount`. `classify(err)` from `@struktoai/mirage-core/errors/classify` names either. |
| Shell | A line on stderr, `cat: /data/x: No such file or directory`, and the command's exit status. |
| [HTTP](https://docs.mirage.strukto.ai/home/access/http.md#errors) | `{detail, errno}` with the status above, plus a `refusal` record when a policy refused the call. |
| [RPC](https://docs.mirage.strukto.ai/home/access/rpc.md#errors) | `-32004` for `ENOENT` and `-32603` for the rest, with `{detail, errno}` in `data`. |
| [MCP](https://docs.mirage.strukto.ai/home/access/mcp.md#tools) | The tool's answer with `isError` set: `Error: /data/x: No such file or directory`. |
| [FUSE](https://docs.mirage.strukto.ai/home/setup/fuse.md) | The host's errno number. A failure with no errno reads as `EIO`. |
| SFTP | An SFTP status code, such as `3` for permission denied and `4` for a general failure. |
| NFS | An NFS3 status code, such as `NFS3ERR_NOTSUPP` (`10004`) for an unsupported call. |
| [Runtimes](https://docs.mirage.strukto.ai/home/setup/runtime/overview.md) | The guest's own error: an `OSError` with its errno in Python, the WASI errno in a WebAssembly guest. |

## Shell lines

A line that runs to its end answers `exit_code`, `stdout` and `stderr`. A
non-zero status is the line's result, not a failed call: HTTP answers `200`, RPC
a result, and MCP sets `isError`. Canceling the request is a failed call
instead: HTTP answers `499` and RPC the error `-32800`. A command's stderr
follows GNU coreutils, and its status is the one the real command exits with.
These statuses come from the shell itself:

| Status | Means |
| - | - |
| `0` | Success. |
| `1` | The command failed. |
| `2` | A usage or syntax error. Some commands use their own (`git` exits `128` and `129`). |
| `124` | The line, or `timeout`, ran past its time limit. |
| `126` | The command was found but not run: it is not executable, a policy refused it, no runtime takes it, or its argument list is too long, as a glob past a mount's [`walk_limit`](https://docs.mirage.strukto.ai/home/integration/search#walk_limit) is. |
| `127` | The command was not found, or an unset variable was read under `set -u`. |
| `128` + n | Signal n ended it: `130` for an interrupt (the CLI and SSH report a Ctrl-C so), `141` for a write to a closed pipe. |
| `254` | The session's `processes.max` refused a fork. |

## Service errors

A command that reaches a service through a mount reports the service's failure
as the condition it maps to, or in the service's own words after the command's
name. An [account CLI](https://docs.mirage.strukto.ai/home/setup/clis.md) such as `gh` or `ntn` reports
a service error the way the real CLI does, with its wording and exit status.


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