Skip to content
Files SDK
Esc
↑↓navigate↵open⌘Jpreview
On this page

Errors

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.

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 or a timeout rather than the provider. Both surface as code: "Provider", so this flag is how you tell an abort apart from a genuine provider failure.
  • timedOut — true when the abort came from a configured timeout rather than your own signal. A timeout sets aborted too, so check timedOut to tell “the backend hung” apart from “the caller cancelled”.
  • permanent — true when re-issuing the same request can only fail the same way, so it’s not retried. Always true for Invalid, Unsupported, and ReadOnly; set on a Provider failure only when it’s deterministic (a host that ignores Range, corrupt stored data).
  • applied — true when a conditional mutation committed at the provider before the call rejected (an awaited plugin threw after next(), or a post-commit check failed). The object changed even though you got an error; appliedEtag carries the committed generation for uploads. Reconcile with an exact read instead of retrying the same predicate. Never set on a veto or a 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.
  • "Invalid" — the call itself is wrong: an empty or .. key, a malformed range, ETag, or condition, a contradictory option, bad constructor config, or a file a validation() rule rejects. Fix the call; retrying it can’t help.
  • "Unsupported" — the call is well-formed, but this adapter (in this mode, with these plugins) can’t do it: a range on an adapter without range reads, metadata on Vercel Blob, url() under encryption(), a signedUploadUrl() maxSize the provider can’t enforce. Check files.capabilities to branch before calling.
  • "Provider" — the backend or transport failed: network errors, throttling, 5xx responses, timeouts, and aborts. Inspect cause for the underlying error.

NotFound, Unauthorized, Conflict, and Provider come from the provider’s own error code and HTTP status (404 → NotFound, 401 / 403 → Unauthorized, 409 / 412 → Conflict, everything else → Provider). ReadOnly, Invalid, and Unsupported are the SDK’s own, raised before any provider I/O wherever the SDK can tell. Only Provider failures are retried, and not when they’re aborted or permanent; the rest are deterministic and returned to you immediately.

Through the gateway, Invalid is answered as a 422 with the wire code Validation and Unsupported as a 422 with the wire code Unsupported; the browser client turns both back into the matching FilesError code.

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.

Last updated on

Was this page helpful?