{"record":{"id":"467103cdea5b17ad","repo":"payloadcms/payload","slug":"staged-upload-was-not-found","errorCode":null,"errorMessage":"Staged upload was not found.","messagePattern":"Staged upload was not found\\.","errorType":"exception","errorClass":"APIError","httpStatus":400,"severity":"error","filePath":"packages/payload/src/uploads/stagedUpload.ts","lineNumber":178,"sourceCode":"  ) {\n    throw new APIError('Invalid staged upload.', 400)\n  }\n\n  const { uploadId } = uploadReference\n  const upload = await verifyUploadID(req, uploadId)\n\n  if (upload.collectionSlug !== collectionSlug || upload.user !== getUser(req)) {\n    throw new Forbidden(req.t)\n  }\n\n  const directory = await getUploadDirectory(req, upload.collectionSlug)\n  const tempFilePath = path.join(directory, upload.id)\n  let data: Buffer\n\n  try {\n    data = await fs.readFile(tempFilePath)\n  } catch {\n    throw new APIError('Staged upload was not found.', 400)\n  }\n\n  if (data.length !== upload.filesize) {\n    await fs.rm(tempFilePath, { force: true })\n    throw new APIError('Staged upload is incomplete.', 400)\n  }\n\n  await fs.rm(tempFilePath, { force: true })\n\n  return {\n    name: upload.filename,\n    data,\n    mimetype: upload.mimeType,\n    size: data.length,\n  }\n}\n\n/**","sourceCodeStart":160,"sourceCodeEnd":196,"githubUrl":"https://github.com/payloadcms/payload/blob/00c58b35c0ed348ddc22daabf467b139727214fd/packages/payload/src/uploads/stagedUpload.ts#L160-L196","documentation":"Thrown by `getStagedFile` when reading the temp file from disk fails (the `fs.readFile` call rejects). The staged upload JWT is valid and the user/collection match, but the underlying file on disk is gone.","triggerScenarios":"The temp file was already consumed and deleted by a prior `getStagedFile` call (each call deletes the file), or `removeExpiredUploads` cleaned it up after the one-hour window, or the temp directory was cleared by an external process / container restart.","commonSituations":"Calling create/update twice with the same uploadId (second call finds no file); the server restarted and temp files are on ephemeral storage; the one-hour JWT window expired and the cleanup sweeper removed the file; a deployment wiped the `tempFileDir`.","solutions":["Treat an uploadId as single-use: stage -> PUT bytes -> consume once. Do not retry the document create with the same uploadId.","If the operation failed transiently, re-stage the file from scratch (new instructions, re-upload bytes).","Ensure persistent or sufficiently long-lived temp storage if your workflow may delay the document create beyond a few minutes.","Check that `upload.tempFileDir` is not pointing at a container-local path that is lost on redeploy."],"exampleFix":"// before -- retrying create with same uploadId after a transient failure\ntry { await createWithUpload(uploadId) } catch { await createWithUpload(uploadId) } // 2nd call: file gone\n\n// after -- re-stage on failure\ntry {\n  await createWithUpload(uploadId)\n} catch {\n  const instr = await generateStagedUploadInstructions({ ... })\n  await putBytes(instr)\n  await createWithUpload(instr.file.uploadReference.uploadId)\n}","handlingStrategy":"try-catch","validationCode":"// Before consuming, ensure you are within the 1-hour window\nconst elapsed = Date.now() - stagedAt\nif (elapsed > 55 * 60 * 1000) {\n  // re-stage before it expires\n}","typeGuard":null,"tryCatchPattern":"try {\n  await payload.create({ collection, data })\n} catch (e) {\n  if (e instanceof APIError && e.message === 'Staged upload was not found.') {\n    // file is gone -- must re-stage from scratch\n    const fresh = await generateStagedUploadInstructions({ ... })\n    await putStagedBytes(fresh)\n    await payload.create({ collection, data: { ...data, file: { uploadReference: { uploadId: fresh.file.uploadReference.uploadId } } } })\n  } else throw e\n}","preventionTips":["Treat each uploadId as single-use: stage -> PUT -> consume exactly once.","Complete the full flow within the one-hour token window.","Do not retry document creation with the same uploadId."],"tags":["upload","staged-upload","file-not-found","transient"],"backgroundTag":null,"analyzedSha":"00c58b35c0ed348ddc22daabf467b139727214fd","analyzedAt":"2026-08-12T20:45:03.758Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}