Repository navigation
Error Codes storage
github-actions[bot] edited this page Nov 16, 2026
·
2 revisions
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 |
Ultimate — v31.44.0 As of 2026-10. The full-stack framework where the primary developer is an AI agent: bunx create-ultimate myapp → Getting started · live demo. MIT licensed. What npm serves is npm view @ultimat3/core version, never this line, and this footer is the only page that stamps a version.
Repository · Issues · Changelog · llms.txt
Edits to these pages are synced from wiki/ in the repository — change the file there, not the wiki, or the next sync overwrites it.
Start
- Getting started
- Installation
- Shapes
- Bare VM
- Project layout
- Migrating an existing app
- Compared to other stacks
Tutorials
- 1 · First app
- 2 · First feature
- 3 · Auth and admin
- 4 · Jobs and realtime
- 5 · Deploy free
- 6 · Growing up
Primitives
- The eight primitives
- Building your own base
- Actions
- Entities and migrations
- Policies and authz
- Queries and live queries
- Client data
- Jobs and workflows
- Scheduled tasks
- Routes and render modes
Capabilities
- Realtime
- Caching and invalidation
- Batching and preloading
- N+1 detection
- PWA and offline
- Client navigation
- MCP and AI
- Agents
- Admin dashboard
- Scraping
- Auth
- Notify
- Storage and uploads
- Feature flags
- SEO
- Static assets
Cross-cutting
- I18n
- Theming
- UI components
- Interface rules
- Timezones and dates
- Money
- Outbound HTTP
- Resource management
- Migrations and backfills
- Testing
- CI: the gate across parallel jobs
Reference