{"record":{"id":"e1eea04d37da11aa","repo":"payloadcms/payload","slug":"invalid-staged-upload","errorCode":null,"errorMessage":"Invalid staged upload.","messagePattern":"Invalid staged upload\\.","errorType":"exception","errorClass":"APIError","httpStatus":400,"severity":"error","filePath":"packages/payload/src/uploads/stagedUpload.ts","lineNumber":161,"sourceCode":" * it, and the temporary file is deleted after it is read.\n */\nexport const getStagedFile = async ({\n  collectionSlug,\n  req,\n  uploadReference,\n}: {\n  collectionSlug: string\n  req: PayloadRequest\n  uploadReference: unknown\n}): Promise<File> => {\n  if (\n    !uploadReference ||\n    typeof uploadReference !== 'object' ||\n    Array.isArray(uploadReference) ||\n    !('uploadId' in uploadReference) ||\n    typeof uploadReference.uploadId !== 'string'\n  ) {\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  }","sourceCodeStart":143,"sourceCodeEnd":179,"githubUrl":"https://github.com/payloadcms/payload/blob/00c58b35c0ed348ddc22daabf467b139727214fd/packages/payload/src/uploads/stagedUpload.ts#L143-L179","documentation":"Thrown by `getStagedFile` when the `uploadReference` object passed to a document create/update is structurally invalid -- it must be a non-null, non-array object containing a string `uploadId`. This reference is what links a document mutation to the bytes previously staged via the signed upload URL.","triggerScenarios":"A create/update request sends `file: { uploadReference: ... }` where `uploadReference` is undefined, a primitive, an array, missing the `uploadId` key, or has a non-string `uploadId`.","commonSituations":"Client code constructs the `uploadReference` manually instead of echoing back the object from `generateStagedUploadInstructions`; a serialization layer (e.g. FormData) dropped the nested object; the client is using an older API shape that passed a plain filename string.","solutions":["Pass the `uploadReference` object exactly as returned by `generateStagedUploadInstructions` -- do not reconstruct it.","Ensure the value is JSON-serializable and survives any FormData / nested-field encoding (check that nested objects are not stringified twice or flattened).","Validate the shape client-side before the request (see validationCode).","If migrating from a legacy upload flow, update the client to use the staged-upload `uploadReference` shape."],"exampleFix":"// before\nawait payload.create({\n  collection: 'media',\n  data: { file: { uploadReference: myUploadId } }, // uploadId at wrong level\n})\n\n// after\nconst instructions = await payloadUploadApi.getInstructions(...)\nawait payload.create({\n  collection: 'media',\n  data: {\n    file: { uploadReference: { uploadId: instructions.file.uploadReference.uploadId } },\n  },\n})","handlingStrategy":"type-guard","validationCode":"// Validate the uploadReference shape before sending\nfunction isValidUploadReference(v) {\n  return !!v && typeof v === 'object' && !Array.isArray(v)\n    && 'uploadId' in v && typeof v.uploadId === 'string'\n}\nif (!isValidUploadReference(file.uploadReference)) {\n  throw new Error('uploadReference must be { uploadId: string }')\n}","typeGuard":"const isUploadReference = (v) => !!v && typeof v === 'object' && !Array.isArray(v) && 'uploadId' in v && typeof v.uploadId === 'string'","tryCatchPattern":"try {\n  await payload.create({ collection, data })\n} catch (e) {\n  if (e instanceof APIError && e.message === 'Invalid staged upload.') {\n    // regenerate instructions and retry\n  } else throw e\n}","preventionTips":["Echo back the uploadReference object exactly as returned by generateStagedUploadInstructions.","Add a client-side type guard before submitting the document create/update.","Avoid manually constructing the uploadReference; always use the SDK-provided value."],"tags":["upload","staged-upload","validation","api-contract"],"backgroundTag":null,"analyzedSha":"00c58b35c0ed348ddc22daabf467b139727214fd","analyzedAt":"2026-08-12T20:45:03.758Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}