---
title: Errors
description: Every method throws a single FilesError with a normalized code, the original provider error on cause, and an aborted flag for timeouts and cancellations.
---

Every single-key method throws a `FilesError` on failure. It collapses the dozens of provider-specific error shapes into one type with a small `code` enum, while keeping the original error on `cause` so nothing is lost.

```ts lineNumbers
import { FilesError } from "files-sdk";

try {
  await files.download("missing.png");
} catch (err) {
  if (err instanceof FilesError && err.code === "NotFound") {
    // handle gracefully
    return null;
  }
  throw err;
}
```

## Properties

- **`code`** — one of the normalized codes below. Match on this for control flow.
- **`message`** — a human-readable summary, taken from the provider error where one is available.
- **`cause`** — the original provider error, untouched. Reach into it for provider-specific detail: `@aws-sdk` errors, for instance, carry a request ID and HTTP status on `$metadata` and a typed `name` like `NoSuchKey`.
- **`aborted`** — `true` when the failure came from a [cancellation](/cancellations) or a [timeout](/timeouts) rather than the provider. Both surface as `code: "Provider"`, so this flag is how you tell an abort apart from a genuine provider failure.

## Codes

- `"NotFound"` — the key (or bucket / container) does not exist.
- `"Unauthorized"` — credentials missing, expired, or insufficient for the operation.
- `"Conflict"` — a precondition failed, e.g. a conditional write that lost a race.
- `"ReadOnly"` — the operation tried to mutate a read-only `Files` instance.
- `"Provider"` — anything else, including network failures, throttling, timeouts, and aborts. Inspect `cause` for the underlying error.

Codes are derived from the provider's own error code and HTTP status (`404` → `NotFound`, `401` / `403` → `Unauthorized`, `409` / `412` → `Conflict`) plus one SDK-native code: `ReadOnly` for write attempts against `new Files({ readonly: true })` or `files.readonly()`. Everything else maps to `Provider`. Only `Provider` failures are [retried](/retries); the rest are deterministic and returned to you immediately.

## Errors in bulk operations

The array forms — `upload([…])`, `download([…])`, `delete([…])`, `head([…])`, `exists([…])` — don't throw on partial failure. Each resolves to a structured result that collects per-key failures in an `errors[]` array (each entry a `{ key, error: FilesError }`) alongside the successes, both in the order you supplied. One bad key never sinks the whole batch. See each method's page for the exact result shape.

> **Logging note:** `cause` can carry request IDs, response headers, and partial request metadata from `@aws-sdk` and friends. If you forward a `FilesError` to logs that cross a trust boundary, strip or whitelist `cause` rather than `JSON.stringify`-ing the whole thing.

For provider-by-provider error gotchas and debugging tips, see [Troubleshooting](/troubleshooting).