File errors

Apps and container instances let you read and change the files on their persistent volumes — in the portal, see Files and Browse files, and through these routes under /boundaries/{boundaryId}/resourcegroups/{resourceGroupName}/resources/{type}/{name}, where {type} is apps or containerinstances:

Route	What it does
GET /files?path=&component=	Lists a directory
GET /files/download?path=&component=	Downloads a file
GET /files/archive?path=&component=	Downloads a directory as a .tar archive
POST /files/upload?path=&name=&component=	Uploads the request body as the file name in the directory path
POST /files/directory	Creates a directory, {"path": "…", "component": "…"}
POST /files/move	Renames or moves a file or directory, {"from": "…", "to": "…", "component": "…"}
DELETE /files?path=&component=&recursive=	Deletes a file, or a directory with recursive=true

Reading needs apps/readFiles or containerinstance/readFiles; changing needs apps/writeFiles or containerinstance/writeFiles.

The error body

A file route answers an error in the problem format: title is a sentence such as "This app is not running.", detail adds to it or is empty, and code is one of the codes below. module is apps or containerinstances, whichever serves the route; the codes are documented here, under the platform's core, because they mean the same for both. No code adds fields of its own.

A 502 reaches you with only error, code, module and correlationId — see Errors from the gateway.

The access checks come first and use the platform-wide codes: a resource that does not exist answers 404 with NOT_FOUND, and a missing permission answers 403 with FORBIDDEN. Those are not the same codes as the lowercase not_found and forbidden on this page.

A download or archive that fails after the transfer has started ends with a broken connection instead of an error body.

The resource and its volumes

no_pods

Status 409, on every file route.

The app or instance is not running: it is stopped or scaled to zero, so there is nothing to read the files through. detail reads "Start the app to manage its files." (or the instance).

What to do: start the app or instance, and try again.

no_agent

Status 409, on every file route.

The resource is running, but none of its pods can serve files: it has no persistent volume, or it was created before file browsing was available and has not been restarted since.

What to do: add persistent storage to the resource, or restart it so that it gets file browsing.

unknown_component

Status 404, on every file route that takes component.

component names no component with a volume to browse — either no such component exists, or it has no persistent volume. detail is empty.

What to do: check the name. A successful listing reports the component it read in its component field.

ambiguous_component

Status 400, on every file route.

The request names no component, and more than one component of the resource has a volume — for example an app with deployment slots, or a container instance with several components that have storage.

What to do: say which one with component.

Paths

forbidden_path

Status 403, on every file route.

The path is not inside one of the resource's volumes: it is not absolute, contains control characters, climbs out with .., or lies outside the volumes the listing reports in roots. For a move this applies to both from and to. A download, archive or delete without a path answers this code too. detail is empty.

What to do: use an absolute path under one of the roots.

forbidden

Status 403, on every file route.

The resource refused the path when it came to act on it. title is the same as for forbidden_path; detail tells the cases apart:

• "path is outside the volumes this agent serves" — the path passes through a symbolic link that leads out of the volume, or one end of a move lies outside the volumes;
• "permission denied" — the file system does not allow the operation on this file or directory;
• "cannot delete the volume root itself" — a delete of a volume's top directory.

What to do: choose another path, or change the file's permissions from inside the resource.

not_found

Status 404, on every file route.

The path does not exist: the directory to list, the file or directory to download, move or delete, or the directory an upload goes into.

What to do: list the parent directory again to see what is there. Create a missing directory with POST /files/directory before uploading into it.

exists

Status 409, mainly on the move route.

The destination of a move already exists.

An upload replaces an existing file of the same name, and creating a directory that already exists succeeds; neither answers with this code.

What to do: choose another destination, or delete the existing one first.

is_a_directory

Status 400, on the download, upload and delete routes.

The operation needs a file but the path is a directory: a download of a directory, an upload whose name is an existing directory, or a delete of a directory without recursive=true.

What to do: download a directory with /files/archive, choose another name for the upload, or delete with recursive=true — which deletes everything in the directory.

not_a_directory

Status 400, on the list and archive routes.

The operation needs a directory but the path is a file. A symbolic link counts as a file, also when it points to a directory.

What to do: download a file with /files/download, or list the directory it is in.

Uploads

too_large

Status 413, on the upload route.

The upload's Content-Length is larger than the module accepts for one upload. detail gives the module's limit in bytes. An upload can also be refused before it reaches the module, with another status and without this code.

What to do: upload a smaller file, or split it into several.

invalid_argument

Status 400, on the upload route.

The upload is missing something it needs, and detail says what: the directory in path, a file name in name (a name that ends in / has none), or a Content-Length header — an upload sent in chunks has none.

What to do: add what detail names. When detail names none of these, report it with the correlationId.

size_mismatch

Status 400, on the upload route.

Fewer bytes arrived than the upload's Content-Length announced; usually the connection broke off during the upload. detail gives both numbers.

What to do: upload the file again.

Failures on the volume or the platform

io_error

Status 502, on every file route.

The volume failed the operation — for example because it is full or read-only. The file system's reason is in detail, which is left out when the 502 reaches you through the gateway (see The error body). Some requests that cannot succeed as asked are reported this way as well: a move into a directory that does not exist or onto another volume, a directory created where a file is in the way, a listing of a path that runs through a file, and a delete that the file system does not permit.

What to do: check that the volume has free space and is writable, and that the request is not one of the cases above. Otherwise retry, and report it with the correlationId if it persists; the platform's logs have the reason.

channel_error

Status 502, on every file route.

The platform could not look up the resource's pods in its cluster.

What to do: retry shortly. If it persists, report it with the correlationId.

no_result_frame

Status 502, on every file route.

The platform ran the operation in the resource's pod but got no answer it could read — including when it could not run the operation there at all.

What to do: retry; if it fails again, restart the resource. If it persists, report it with the correlationId.

unsupported_protocol

Status 502, on every file route.

The file browsing component in the resource's pods is a different version from the one the platform expects.

What to do: restart the resource so that it gets the current version. If that does not help, report it to your platform administrator.