{"record":{"id":"780645e24c66efd3","repo":"payloadcms/payload","slug":"invalid-upload-reference","errorCode":null,"errorMessage":"Invalid upload reference.","messagePattern":"Invalid upload reference\\.","errorType":"http","errorClass":"APIError","httpStatus":400,"severity":"error","filePath":"packages/payload/src/uploads/getFileFromUploadInstructions.ts","lineNumber":22,"sourceCode":"import { APIError } from '../errors/APIError.js'\nimport { getStagedFile } from './stagedUpload.js'\n\nexport const getFileFromUploadInstructions = async ({\n  collectionSlug,\n  file,\n  req,\n}: {\n  collectionSlug: string\n  file: UploadInstructions['file']\n  req: PayloadRequest\n}): Promise<NonNullable<PayloadRequest['file']>> => {\n  if (\n    !file ||\n    typeof file !== 'object' ||\n    !file.uploadReference ||\n    typeof file.uploadReference !== 'object'\n  ) {\n    throw new APIError('Invalid upload reference.', 400)\n  }\n\n  /**\n   * Handlers fetch files uploaded to a storage provider. An uploadId points to a temporary file\n   * already stored by Payload, so no handler is needed.\n   */\n  if ('uploadId' in file.uploadReference) {\n    return getStagedFile({ collectionSlug, req, uploadReference: file.uploadReference })\n  }\n\n  const uploadConfig = req.payload.collections[collectionSlug]!.config.upload\n\n  if (!uploadConfig || !uploadConfig.handlers) {\n    throw new APIError('uploadConfig.handlers is not present for ' + collectionSlug)\n  }\n\n  let response: null | Response = null\n  let error: unknown","sourceCodeStart":4,"sourceCodeEnd":40,"githubUrl":"https://github.com/payloadcms/payload/blob/00c58b35c0ed348ddc22daabf467b139727214fd/packages/payload/src/uploads/getFileFromUploadInstructions.ts#L4-L40","documentation":"`getFileFromUploadInstructions` expects `file` to be an object carrying an `uploadReference` that is itself a non-null object. If `file` is falsy, not an object, lacks `uploadReference`, or `uploadReference` is not an object, it throws `APIError` HTTP 400 `Invalid upload reference.` This guards the branch that decides between a staged upload (`uploadId`) and an adapter handler call.","triggerScenarios":"A document create/update where the `file` payload (the `UploadInstructions['file']` shape returned by `/upload-instructions`) is missing, not an object, or its `uploadReference` is absent/not an object. Typically the client dropped or reshaped the `file` block returned by the instructions endpoint.","commonSituations":"The client stored only `filename`/`mimeType` and omitted `uploadReference`. A version mismatch: the client speaks an older upload protocol without `uploadReference`. A serialization step (JSON round-trip) dropped the key. The frontend sent `file: uploadInstructions.file.uploadReference` (one level too deep).","solutions":["Pass the **entire** `file` object returned by `POST /upload-instructions` unchanged into the document request: `file: instructions.file` (which includes `uploadReference`).","Update the client SDK to the Payload version that emits `uploadReference`.","Log the exact `file` value sent to find the dropped/renamed key.","If building instructions manually, include `uploadReference: { uploadId }` (staged) or the adapter-specific reference object."],"exampleFix":"// before — client sent only the filename\nawait payload.create({\n  collection: 'media',\n  data: { file: { filename: 'a.png' } }, // missing uploadReference\n})\n\n// after — pass the full file object from the instructions response\nconst instructions = await getUploadInstructions({ collectionSlug: 'media', filename, filesize, mimeType, req })\nawait payload.create({\n  collection: 'media',\n  data: {},\n  file: instructions.file, // { filename, mimeType, size, uploadReference }\n})","handlingStrategy":"type-guard","validationCode":"function hasValidUploadReference(file: unknown): boolean {\n  return !!file && typeof file === 'object' &&\n    !!(file as any).uploadReference &&\n    typeof (file as any).uploadReference === 'object'\n}\n\nconst file = instructions.file\nif (!hasValidUploadReference(file)) {\n  throw new Error('uploadReference missing on file payload')\n}","typeGuard":"type UploadFile = { filename: string; mimeType: string; size: number; uploadReference: Record<string, unknown> }\nfunction isUploadFile(file: unknown): file is UploadFile {\n  return !!file && typeof file === 'object' &&\n    typeof (file as any).filename === 'string' &&\n    typeof (file as any).mimeType === 'string' &&\n    !!file && typeof (file as any).uploadReference === 'object' && (file as any).uploadReference !== null\n}","tryCatchPattern":"try {\n  await payload.create({ collection: 'media', data, file })\n} catch (err) {\n  if (err instanceof Error && /invalid upload reference/i.test(err.message)) {\n    // re-request instructions and pass the full instructions.file object\n  } else throw err\n}","preventionTips":["Pass the entire `instructions.file` (including `uploadReference`) into the document request.","Keep client SDK in sync with the Payload version's upload protocol.","Never strip `uploadReference` when serializing the instructions response."],"tags":["upload","type-validation","request-shape","upload-reference"],"backgroundTag":null,"analyzedSha":"00c58b35c0ed348ddc22daabf467b139727214fd","analyzedAt":"2026-08-12T20:45:03.758Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}