Skip to content

Error Codes storage

github-actions[bot] edited this page Nov 16, 2026 · 2 revisions

Error codes: @ultimat3/storage

Part of Error codes: every code @ultimat3/storage registers. x errors explain <CODE> --json prints the same row.

Code Means Typical cause Fix
X_STORAGE_ALREADY_PROMOTED the upload was already promoted onto its row promoteAttachment found the pending key gone and the attached key present: an earlier call moved these bytes, most often a confirm retried or sent twice. It used to answer the attached object as if this call had moved it, so a caller inserted a second row for it and the cleanup of that failed insert deleted the first row bytes await disk.stat(meta.attachedKey) answers the moved object: answer the row that references that key if one exists, write it with that key if none does, and never delete the key on a failure of your own
X_STORAGE_CHECKSUM_MISMATCH bytes do not match the declared checksum a truncated upload, or a sha256 computed over different bytes than the ones sent checksum: sha256Base64(bytes) — over the exact bytes you send; or omit checksum and let the driver hash
X_STORAGE_DELETE_FAILED the object could not be deleted the provider refused — a denied s3:DeleteObject, a throttle, an expired credential, a read-only mount. Deleting an absent key stays idempotent and never reaches here; everything else does, because the alternative shipped for a year: a .catch(() => undefined) turned 200 denied deletes into 200 successes and an erasure sweep reported data gone that was still there the fix is the driver's own, so it reproduces the refusal with the provider's words — a generic one is a round trip
X_STORAGE_DISK_UNKNOWN no disk with that name is configured disk('<name>') for a disk storage.disks never declared disk('<one of the names cause lists>') — or declare "<name>" in defineStorage({ disks }) in app.config.ts
X_STORAGE_KEY_CONFLICT the key collides with another key on a local or memory disk the local driver stores an object as a file at its key, so one key cannot be both an object and the directory of another: put('a') then put('a/b'), or the reverse — or a beside a.json/b, which collide in the sidecar tree. Refused before a byte moves; it was a bare ENOTDIR / EISDIR. s3Driver and memoryStorageDriver hold both disk("<disk>").list({ prefix: "a" }) with the name the disk is registered under — lists the object in the way (the cause names it); store one of the two under a different key
X_STORAGE_KEY_UNSHARED object key is outside every tenant and every shared prefix a read through /_storage or /media named a key that is not under org// and not under a prefix the app listed in defineStorage({ shared }); refused as 404 so the answer never confirms the object exists scopedKey(orgId, ...parts) for a tenant's object; for one every reader may have, defineStorage({ disks, shared: { uploads: ['brand/'] } }) with your own disk and prefix
X_STORAGE_LIST_FAILED the objects could not be listed the disk refused a listing — a denied s3:ListBucket, a throttle, an expired credential, a root this process cannot read. A disk nobody has written to yet is honestly empty and answers an empty page; everything else reaches here, because sweepOrphans walks list() and a swallowed refusal certifies a prefix nothing could see as having no orphans the fix is the driver's own — ls -ld <root> on local, aws s3api list-objects-v2 --bucket <bucket> on s3 — so it reproduces the refusal with the disk's own words
X_STORAGE_MULTIPART_UNSUPPORTED this disk cannot take an upload in parts a custom StorageDriver declares no multipart capability, and grantMultipart was asked to open a session on it implement StorageDriver.multipart on the driver, or grant one PUT with grantUpload({ disk, orgId, request })
X_STORAGE_NOT_FOUND no object at that key a stale key, the wrong disk, or an object already deleted list the prefix and compare: await disk('<disk>').list({ prefix: '<dir>' })
X_STORAGE_NOT_PENDING the key is not a pending upload promoteAttachment was handed a key outside the org pending/ prefix — most often an already-attached key a client sent back. It checked only that the key was inside the org, so another row file was copied onto this row and the original deleted from the victim promoteAttachment({ disk, key: pendingKey(orgId, name), orgId, target }) — the key grantUpload returned with no target; an attached key already belongs to a row, so promote the pending upload the client just sent
X_STORAGE_OBJECT_CHANGED the object changed while it was being promoted the pending object is not the revision promoteAttachment read: the upload URL stays valid until it expires, so the uploader overwrote it between the sniff and the copy promoteAttachment({ disk, key, orgId, target, policy }) once the upload has finished: it reads the object again
X_STORAGE_OBJECT_LOCKED the object is under retention or a legal hold a delete, overwrite or copy onto a key whose retention has not lapsed, or whose legal hold is on, was refused; the stored bytes are unchanged disk(name).retentionOf(key) — shows the lock and its retainUntil; write to a new key, or wait until it lapses
X_STORAGE_ORG_MISMATCH object key belongs to another org a key from one tenant used while the actor resolves to another; the signature can be perfectly valid and this still fires scopedKey('<orgId>', ...parts) — and pass the actor's org as orgId, never one read off the request
X_STORAGE_PARTS_INVALID the parts named do not match the parts stored completeUpload was handed a part the disk never received, parts out of ascending order, or an etag that is not the stored one listParts({ disk, orgId, key, uploadId }) to see what landed, resend the missing part, then completeUpload again
X_STORAGE_PATH_UNSAFE object key escapes its prefix an absolute key, a .. segment, or a backslash scopedKey(orgId, ...parts) — builds the key relative, with forward slashes and no ..
X_STORAGE_PUT_FAILED the object could not be written the disk refused a put() or copy() — a root this process cannot write (EACCES), a full or read-only volume (ENOSPC, EROFS), or a provider that answered the write with a refusal. It surfaced as a bare filesystem Error or a bare S3Error; nothing was stored, and any existing object at the key is untouched. local: ls -ld <root> && df -h <root> with the disk's own root, which the error prints. s3: aws s3api get-bucket-policy --bucket <bucket>
X_STORAGE_QUARANTINED the object is still in quarantine the uploadScanner installed in runtime.ts answered hold for this upload (a review queue, an async vendor scan); the per-attempt copy is deleted, the upload stays pending and nothing is attached. No upload policy overrides a hold promoteAttachment({ disk, key: '<pending key>', orgId, target, policy }) # again once your scanner answers clean for this pendingKey — sweepOrphans collects it if it never does
X_STORAGE_RANGE_UNSATISFIABLE the requested byte range starts past the end of the object get(key, { range: [first, last] }) named a first byte at or past the object's size — an empty object has no byte to start at await disk.get(key, { range: [0, size - 1] }) # any first byte below the size; an empty object: await disk.get(key)
X_STORAGE_READ_FAILED the object could not be read the disk refused a get(), stat(), exists(), stream() or the read half of a copy() — a denied s3:GetObject, a throttle, an expired credential, an unreadable file (EACCES, EIO). It surfaced as a bare S3Error or a bare filesystem Error. An object that is simply not there is X_STORAGE_NOT_FOUND, never this. local: ls -l <root>/<key>. s3: aws s3api head-object --bucket <bucket> --key <key>. The error prints the command with the real root, bucket and key
X_STORAGE_SCAN_UNAVAILABLE the upload scanner could not give a verdict the uploadScanner installed in runtime.ts rejected (daemon down, timeout, file past its limit), or the per-attempt copy could not be read for it, and the upload policy fails closed; the attempt copy is deleted and the upload stays pending promoteAttachment({ disk, key, orgId, target, policy }) # again once the scanner answers — or uploadPolicy({ onScanUnavailable: 'accept' }) to promote unscanned files
X_STORAGE_TARGET_UNSCANNED a targeted upload grant would bypass the upload scanner grantUpload or grantMultipart was given a target while an uploadScanner is installed in runtime.ts; a targeted key never passes through promoteAttachment, so its bytes would reach the row unscanned grantUpload({ disk, orgId, request, policy }) — no target — then promoteAttachment({ disk, key, orgId, target, policy }) once the upload lands
X_STORAGE_TOO_LARGE payload exceeds the upload size limit a file over the policy's maxBytes; cause carries both numbers uploadPolicy({ maxBytes: <bytes> }) for a higher limit, or compress the file first
X_STORAGE_TYPE_REJECTED content type is not allowed for this upload a type absent from allowedContentTypes, or magic bytes that disagree with the declared Content-Type — the bytes win uploadPolicy({ allowedContentTypes: [...allowed, '<type>'] }) — or re-upload declaring the type cause sniffed: validateUpload({ key, declaredContentType: '<sniffed type>', bytes }, policy)
X_STORAGE_UPLOAD_FAILED the signed upload was refused the presigned PUT answered non-2xx, or never reached the disk (status: 0) await uploadFile({ file, grant }) — again, for a fresh grant; a 4xx here is the constraint named in the body, not a transport fault
X_STORAGE_UPLOAD_INFECTED the upload scanner found malware in the file promoteAttachment ran the uploadScanner installed in runtime.ts over its per-attempt copy (pending/scan/) and it answered infected; the pending upload and that copy are deleted, and the row's key is never written grantUpload({ disk, orgId, request }) for a new, clean file (this one is gone; meta.signature names the detection)
X_STORAGE_UPLOAD_SIZE_UNDECLARED an upload grant was asked for without the size of the file an upload grant was minted, or an s3 PUT signed with a ceiling, naming no whole byte count of at least 1: a presigned PUT binds a size only by signing the exact Content-Length, so there was nothing to bind grantUpload({ disk, orgId, request: { filename, contentType, size: file.size } })
X_STORAGE_UPLOAD_UNKNOWN no open multipart upload has that id the uploadId was never opened on this disk for that key, or it was already completed or aborted grantMultipart({ disk, orgId, request }) again, and upload the parts under the new uploadId
X_STORAGE_URL_EXPIRED signed URL is past its expiry a form left open longer than the grant's window grantUpload({ disk, orgId, request, expiresInMs }) — again; a longer expiresInMs widens the window the signature grants
X_STORAGE_URL_INVALID signed URL does not match its signature an edited constraint (x-max, x-ct, the key), a URL outside the mounted base, a PUT grant replayed as a GET, or a Content-Type header the signature does not cover grantUpload({ disk, orgId, request }) — mint a fresh one and send it unedited; every constraint is inside the signature
X_STORAGE_URL_UNVERIFIABLE nothing can check the signature — no verifier was supplied acceptSignedUpload was called with no secret: and the disk's driver implements no verifySigned. Its own code deliberately, not X_STORAGE_URL_INVALID: "no verifier" and "this signature is forged" need opposite edits, and reporting the first as the second sends an operator hunting an attacker who is not there await acceptSignedUpload({ ...input, secret }) — or implement verifySigned on the driver; a local disk already verifies its own
X_STORAGE_WRITE_OUTCOME_UNKNOWN a write was sent and its answer lost, and the disk could not say whether it landed the connection died after the last request of a write was sent and before the provider answered, and neither a stat of the key nor an abort of the upload could settle whether the object is the one sent await disk.stat(key) — the size and etag now at the key; the same as what was sent means it landed

Clone this wiki locally