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-sdkerrors, for instance, carry a request ID and HTTP status on$metadataand a typednamelikeNoSuchKey.aborted—truewhen the failure came from a cancellation or a timeout rather than the provider. Both surface ascode: "Provider", so this flag is how you tell an abort apart from a genuine provider failure.timedOut—truewhen the abort came from a configuredtimeoutrather than your ownsignal. A timeout setsabortedtoo, so checktimedOutto tell “the backend hung” apart from “the caller cancelled”.permanent—truewhen re-issuing the same request can only fail the same way, so it’s not retried. AlwaystrueforInvalid,Unsupported, andReadOnly; set on aProviderfailure only when it’s deterministic (a host that ignoresRange, corrupt stored data).applied—truewhen a conditional mutation committed at the provider before the call rejected (an awaited plugin threw afternext(), or a post-commit check failed). The object changed even though you got an error;appliedEtagcarries 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-onlyFilesinstance."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 avalidation()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: arangeon an adapter without range reads,metadataon Vercel Blob,url()underencryption(), asignedUploadUrl()maxSizethe provider can’t enforce. Checkfiles.capabilitiesto branch before calling."Provider"— the backend or transport failed: network errors, throttling, 5xx responses, timeouts, and aborts. Inspectcausefor 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:
causecan carry request IDs, response headers, and partial request metadata from@aws-sdkand friends. If you forward aFilesErrorto logs that cross a trust boundary, strip or whitelistcauserather thanJSON.stringify-ing the whole thing.
For provider-by-provider error gotchas and debugging tips, see Troubleshooting.