Limits and errors
Known limitations
- Two machines boot at a time. A fleet of six takes about three boot times to come up. The configuration key
maxParallelBootsinpolicy.jsonchanges 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 keyhostReserveMiBchanges 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
interruptedand removes its machines and disks. Fleet machines keep running, and the service picks them up again when it starts. execcannot show windows. It runs as SYSTEM in session 0. Anything that must appear on the screen starts withdesktop launch.- The desktop user is a standard user. Programs that need administrator rights raise an elevation prompt, which
endia desktop uacanswers in images that setPromptOnSecureDesktopto 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 }
codeis one of the codes below; no other code exists.messagestates what was expected and what was found, in one or two sentences. It never contains a password or a key.fieldPathnames the field at fault: a request member (reference), a Compose path (services.trainee.ports[0]) or a recipe position (recipes/dotnet.Endiafile:3:1).detailscarries 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. | 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. |