# Limits and errors

> The limits the service keeps to, and every error code it returns.

## Known limitations

- **Two machines boot at a time.** A fleet of six takes about three boot times to come up. The configuration key `maxParallelBoots` in `policy.json` changes the number.
- **12 GiB of the PC's memory stays free.** The service refuses to start a machine that would leave less, with `CAPACITY_REFUSED`. The check uses each machine's starting memory, not the most it may grow to. The configuration key `hostReserveMiB` changes the reserve.
- **20 GiB of disk stays free** on the image folder's drive (`minFreeDiskGiB`).
- **A restart of the service** stops any build or import that was running, marks it `interrupted` and removes its machines and disks. Fleet machines keep running, and the service picks them up again when it starts.
- **`exec` cannot show windows.** It runs as SYSTEM in session 0. Anything that must appear on the screen starts with `desktop launch`.
- **The desktop user is a standard user.** Programs that need administrator rights raise an elevation prompt, which `endia desktop uac` answers in images that set `PromptOnSecureDesktop` to 0.
- **Addresses on the Default Switch change** when the PC restarts. Refer to machines by service name, and to the PC by `host-gateway`, rather than by address.

## Error format

Every refusal, and every failed operation, carries one shape:

```json
{ "code": string, "message": string, "fieldPath": string or null, "details": object or null }
```

- `code` is one of the codes below; no other code exists.
- `message` states what was expected and what was found, in one or two sentences. It never contains a password or a key.
- `fieldPath` names the field at fault: a request member (`reference`), a Compose path (`services.trainee.ports[0]`) or a recipe position (`recipes/dotnet.Endiafile:3:1`).
- `details` carries the code's own data, where the table names it.

The command line prints a refusal as `Error response from EastIndia: <message> (<CODE>)`.

## Error codes

| Code | HTTP | Meaning | `details` |
|---|---|---|---|
| `INVALID_REQUEST` | 400 | The request is malformed: bad JSON, an unknown or missing member, a bad header or query value, a body larger than `maxContextBytes`, a purpose title or detail outside its limits, a machine's workload sent without its progress, a stage sent to a machine, or a path that cannot be the new image folder. | |
| `NOT_FOUND` | 404 | The image, machine, fleet, volume, operation, exec, process, program or route named does not exist, or a prefix matches several. | `candidates` for an ambiguous prefix |
| `PERMISSION_DENIED` | 403 | The caller may not use the route: only a caller on the named pipe may issue, list or revoke client certificates or move the image folder. | |
| `INVALID_DEFINITION` | 422 | A recipe, Compose file, ignore file, variable file or Compose value breaks a rule. | |
| `UNSUPPORTED_FIELD` | 422 | Something Docker accepts that this release does not support. | |
| `UNSUPPORTED_FORMAT` | 422 | A body or a disk file is not in a format East India reads. | |
| `CAPABILITY_MISSING` | 422 | The image, machine or user lacks what the request needs. Examples: an import check failed; `--elevated` was asked of a standard desktop user; `desktop uac` was asked where `PromptOnSecureDesktop` is not 0. | `check` and `checks` for an import check |
| `ACTION_UNSUPPORTED` | 422 | The UI element lacks the pattern the action needs, or the action targets a window of a process that runs with higher rights than the desktop helper, which Windows blocks. | |
| `ELEMENT_NOT_FOUND` | 422 | No UI element matches the selector. | `tree` |
| `ELEMENT_AMBIGUOUS` | 422 | Several UI elements match the selector. | `tree` |
| `NAME_IN_USE` | 409 | A name the request would create is taken: a file in the image folder, a machine name used by another fleet, the name of a client certificate that is not revoked, or a new image folder that already holds files. | |
| `RESOURCE_IN_USE` | 409 | What the request would remove or use is in use: an image with tags, children or machines; an attached volume; a disk attached elsewhere; a running, paused or restarting machine that `rm` without `--force` would remove. | `usedBy` |
| `FLEET_CONFLICT` | 409 | The fleet's existing networks differ from the Compose file in a way `up` cannot change. | |
| `NETWORK_CONFLICT` | 409 | A subnet or fixed address overlaps another, or the address pools are exhausted. | |
| `PORT_CONFLICT` | 409 | A published port is already in use on the PC. | |
| `PROGRESS_CONFLICT` | 409 | A workload, the total of a fleet's work, would be held on a fleet and on its machines at once. The message says which holds it. See [Purpose and progress](/docs/testing/purpose-and-progress/#reporting-progress). | `workloadOn` |
| `MACHINE_NOT_RUNNING` | 409 | The machine is not in the state the request needs: most requests need it running and ready; `pause` needs it running, `unpause` needs it paused, and `start` refuses it paused. | |
| `DESKTOP_UNAVAILABLE` | 409 | No signed-in desktop user, a locked session, or a desktop helper that has not reported ready. | |
| `FOCUS_REFUSED` | 409 | The window could not be brought to the foreground, so no input was sent. | |
| `UNEXPECTED_PROMPT` | 409 | The elevation prompt names another program; nothing was typed. | `screenshot` (Base64 PNG), `program` |
| `FILES_LOCKED` | 409 | A file to be replaced or deleted in the machine is in use. | `files` |
| `IDEMPOTENCY_CONFLICT` | 409 | The request's idempotency key was used before with a different request. | |
| `CAPACITY_REFUSED` | 503 | Starting the virtual machine would leave less than `hostReserveMiB` free, or the image's chain of parents would exceed `maxLayerDepth`. | `requiredBytes`, `availableBytes`, `reserveBytes` for memory; `depth` and `maxLayerDepth` for the chain |
| `STORAGE_FULL` | 507 | The image folder's volume would keep less than `minFreeDiskGiB` free. | `requiredBytes`, `freeBytes` |
| `INTEGRITY_FAILED` | 500 | An image's disk file differs from its record. | `path`, `expected`, `found` |
| `GUEST_UNREACHABLE` | 502 | The guest service of a running machine does not answer. | |
| `HYPERV_CONNECTION_FAILED` | 502 | The connection to Hyper-V's management service failed, so the request was not carried out. Not retried: the PC itself needs attention. | |
| `HYPERV_BUSY` | 503 | Hyper-V did not answer in time, or a job it started outlasted its wait, after the request was tried again after 1, 2 and 4 seconds. | |
| `MACHINE_BUSY` | 409 | The machine was changing state, after the request was tried again after 1, 2 and 4 seconds. | |
| `IMAGE_FOLDER_MOVING` | 503 | An image-folder move is running, so the service answers only `GET` routes until it has restarted. | `operationId` |
| `HYPERV_REFUSED` | 500 | Hyper-V refused the request for a reason that retrying does not change. The message carries Hyper-V's own text. | |
| `TIMEOUT` | 504 | A step did not finish within its configured time; the message names the configuration key, or the request field that set the time. | `configKey` when one configuration key sets the whole time, `seconds` |
| `BUILD_FAILED` | operation only | A build step failed. | `line`, `exitCode`, `lastLines` |
| `CANCELLED` | operation only | The operation was cancelled. | |
| `INTERRUPTED` | operation only | The service stopped while the operation was unfinished. | |
| `INTERNAL_ERROR` | 500 | A fault in East India. The message gives the time of the service log line that describes it. | |
