Skip to content

Error codes ​

Every entry of the error list (getErrors(), ErrorEntry) has a code, a message, a stage and a retryable flag. The code is typed ErrorCode, which is KnownErrorCode | (string & {}): the 18 codes below autocomplete, and a backend may send any other string in its JSON error body ({ "code": "...", "message": "..." }).

The stage says which step failed: validate, manifest, status, upload or finalize.

CodeMeaningRetried automatically
NETWORKNo response. Also an abort that core did not start, for example your code calling file.xhr.abort().yes
TIMEOUTThe timeout option elapsed.yes
STALLEDAborted by the stall watchdog (stallTimeout).yes
SERVER_ERROR5xx, 408 or 429 without a code in the body.yes
HTTP_ERRORAnother 4xx without a code in the body.no
AUTH401 or 403. The server's own code in the body wins if it sends one.no
TOO_LARGEOnly when the server sends it in the response body (code). A 413 without a code becomes HTTP_ERROR.no
INVALID_PATHA path with a .. segment (also when a server sends it).no
INVALID_CHUNKThe server rejected a chunk (400).no
CHUNK_MISMATCHThe server answered 409. Without chunkStatusUrl the file fails with it.no
REJECTED_SIZEValidation: larger than maxFilesize.no
REJECTED_TYPEValidation: does not match acceptedFiles.no
MAX_FILESValidation: over maxFiles.no
REJECTEDYour accept() callback rejected the file.no
FINALIZE_FAILEDchunksUploaded reported an error or threw.no
UNREADABLEThe file can no longer be read, for example an iCloud placeholder that is not downloaded (shown with dictFileUnreadable).no
TRANSFORM_FAILEDtransformFile threw.no
REQUEST_SETUP_FAILEDSomething threw while a request was built or handed to the transport (your url, method, timeout, params or paramName function, xhr.open, setRequestHeader, a custom transport). It is reported with reportError, and retryFailedOnly() tries again.no

Retries use retryChunks and retryChunksLimit, with a delay of random(0.5..1) x min(30 s, 1 s x 2^(n-1)) or the server's Retry-After (seconds, at most 60). Network errors, timeouts, 408, 429 and 5xx are retried; 401, 403 and other 4xx are not. Whole-file uploads (no chunking) are never retried automatically.

Offline, hidden-page and lost-connection (unreachable) failures never become entries: they pause the upload instead (see Offline and connectivity). A 4xx or 5xx status is a response, so it never counts as a lost connection.

Your backend sends these codes in its error responses; see the error table in the protocol.

Released under the MIT License.