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 a Provider failure is deterministic, so re-issuing the same request can only fail the same way (a host that ignores Range, an option the adapter can’t honor). Such failures are not retried. Every rejection the SDK raises itself before provider I/O carries it: an unsupported range, metadata, cacheControl, delimiter, or control on an adapter that can’t honor it, a malformed range or condition, and an invalid key.
• 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.
• "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, and not when they’re aborted or permanent; 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.