Running Storage

The STORAGE bucket locally and on Cloudflare, the launch check, serving headers and what to look for in the logs.

The Bucket

apps/web/void.config.ts turns on inference: { bindings: { storage: true } }, because the app reaches the bucket from config/storage.server.ts (Void doesn't scan config/ for bindings). With it:

  • Locally, pnpm dev provides a local STORAGE bucket; files stay on your machine.
  • Deployed, the deploy creates the R2 bucket in your Cloudflare account and binds it. Nothing to set up by hand.

Without it, uploads answer 503 unbound and stored images 503, with an error log naming STORAGE. pnpm kit:doctor --launch flags it as "Uploaded images have somewhere to go".

Serving

GET /api/files/<key> reads no session and never touches the database (SESSIONLESS_PREFIXES in apps/web/lib/sessionless-paths.ts), so images load while the database is down. It answers with:

  • Content-Type: image/webp, X-Content-Type-Options: nosniff, Content-Disposition: attachment
  • Content-Security-Policy: default-src 'none'; sandbox
  • Cross-Origin-Resource-Policy: same-origin (your pages can show it; other sites can't embed it)
  • Cache-Control: public, max-age=31536000, immutable and an ETag

Every miss (unknown, replaced, malformed, a .. path) gets the same 404; malformed keys never reach R2.

Logs

Storage logs keys, kind names, owner ids and error names, never file bytes:

MessageMeans
storage: put failedR2 refused a write: the upload answered 500
storage: delete failed, left for the sweepA best-effort delete failed; the sweep will remove the key
storage: image encoder retired in this isolateMany broken images leaked encoder memory; this Worker instance refuses uploads until Cloudflare recycles it
storage purge finished / storage sweep finishedCounts of a purge or sweep run