Operations

Files and artifacts recovery

Symptom-to-verification for Workspace Files, Command artifacts, and presentation outputs.

Use this when uploads stay pending/pending_scan, downloads return 423, Command attach fails, or a presentation create returns 409/500. Read Workspace Files, Command artifacts, and the Files API first.

There is no public HTTP to run GC or backup restore. Production GC is runDueWorkspaceFileGc (once per UTC day when a batch completes). Backup mirror is workspace-files/backup.ts.

Verify first

Confirm principal: session /api/files?workspaceId= vs v1 workspace API key. Personal keys never mutate v1 Files (403).
GET /api/v1/files/{id} (or session equivalent). Compare status, sizeBytes, sha256.
On preview/production, a 503 on POST/PUT/complete means write readiness failed. details.availability.reasonCode is files_primary_store_unreachable, files_scanner_unreachable, or a config-time files_*_not_configured / files_restore_test_required from capability availability.
Do not treat list absence as proof of GC: list has no status filter; deleted rows can still appear until you inspect status.
Command: with a key that has workspace.secret.read or workspace.write, call GET /api/v1/fluxus-command/jobs/{id} for attachments / artifacts[].incomplete.

Symptom table

Symptom	Verify	Recover
`401` / `403` on v1	Bearer or key `scope`	Use a workspace API key.
`404` on a known file	Key/session workspace vs file `workspaceId`	Call from the owning workspace. Session rejects non-member `workspaceId`.
`400` `idempotency_key_invalid`	Mutation without valid `Idempotency-Key`	Send a key matching the platform pattern (no spaces).
`409` `idempotency_replay_mismatch`	Same key, different body or file id	New key, or replay the original body.
Create `503`	Preview/production readiness	Restore S3/ClamAV (and production backup/restore flags). Replay new keys only after unblock; successful old creates replay from the idempotency store.
`PUT` `409` Only pending files accept content	`status` is not `pending`	Do not overwrite. Create a new file id.
Complete `409` content has not been persisted	Blob `stat` missing	Retry `PUT` with the same content idempotency key, then complete.
Complete `409` Expected N bytes / SHA-256	Body ≠ declared `sizeBytes`/`sha256`	Re-upload matching bytes or recreate metadata.
Stays `pending_scan`	Complete should call `scanFile` in-request	`GET` the file. If another scan holds the 5-minute lease, wait; retry complete with the same key only replays the stored response. Use a new complete key after the lease expires if the first scan never finalized.
`quarantined`	ClamAV `infected`	Do not download (`423`). Treat as unusable; request deletion if policy requires.
`GET` content `423`	`status !== ready`	Wait for clean scan. Command attach/publish will also `423`.
`413`	Over 100 MiB	Shrink the blob.
`416` / `400` range	`Range` not `bytes=start-end`	Single explicit range only.
DELETE still listed	`deletion_requested` is soft-delete	Wait production GC (30 days after request) or accept the row until `deleted`. Live references block GC.
Command attach `423`	File not `ready`	Finish upload+complete+scan first.
Attach failed after first file	Partial `run` refs rolled back	Job should have no attachments; retry `POST` jobs with a new idempotency key and ready ids.
Artifact `incomplete: true`	Default on publish	`POST .../artifacts/{fileId}/complete`.
Artifact `404` on complete	`fileId` never published on that job	Publish first. Job must exist in this workspace.
Presentation `404` image	`fileId` missing in workspace	Same `404` for foreign ids (no ownership leak). Upload a ready PNG/JPEG/GIF ≤ 10 MiB.
Presentation `409` not ready / scan	Input not `ready`, or output scan not clean	Fix Files first. Failed create requests deletion of partial outputs; do not assume PPTX exists.
Presentation `500` then success on retry	Failure is not idempotency-cached	Replay the same `Idempotency-Key`.
Capability `presentation.create` duplicate outputs	Executor omits `idempotencyKey` to the service	Prefer HTTP create for blob-level put keys; treat agent retries as possibly extra Files rows if the HTTP idempotency layer did not wrap the call.

After a stuck upload

GET the file. If pending and blob missing, PUT content then POST complete with keys.
If pending_scan, confirm scanner (ClamAV host) and lease age.
If ready, download GET .../content and check etag.
For Command, publish only after ready; then complete the artifact if incomplete.

What not to do

Do not PUT content onto a non-pending file.
Do not expect DELETE to drop the object immediately.
Do not use a personal API key on /api/v1/files.
Do not pass SVG Workspace Files as presentation image.fileId.
Do not edit docs-site/docs.json or application source to “enable” backup HTTP; it is not implemented as a route.