{"record":{"id":"68313919640ab86d","repo":"payloadcms/payload","slug":"uploadconfig-handlers-is-not-present-for-collect","errorCode":null,"errorMessage":"uploadConfig.handlers is not present for ${collectionSlug}","messagePattern":"uploadConfig\\.handlers is not present for (.+?)","errorType":"http","errorClass":"APIError","httpStatus":500,"severity":"error","filePath":"packages/payload/src/uploads/getFileFromUploadInstructions.ts","lineNumber":36,"sourceCode":"    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\n\n  for (const handler of uploadConfig.handlers) {\n    try {\n      const result = await handler(req, {\n        doc: null!,\n        params: {\n          collection: collectionSlug,\n          filename: file.filename,\n          uploadReference: file.uploadReference,\n        },\n      })\n      if (result) {\n        response = result\n        /**","sourceCodeStart":18,"sourceCodeEnd":54,"githubUrl":"https://github.com/payloadcms/payload/blob/00c58b35c0ed348ddc22daabf467b139727214fd/packages/payload/src/uploads/getFileFromUploadInstructions.ts#L18-L54","documentation":"When `file.uploadReference` has no `uploadId` (i.e. it is an adapter-managed reference, not a staged upload), Payload falls back to the collection's `upload.handlers`. If the collection's `config.upload` is missing or has no `handlers` array, it throws `APIError` (default HTTP 500) `uploadConfig.handlers is not present for <collectionSlug>`. This indicates a misconfigured adapter integration.","triggerScenarios":"`getFileFromUploadInstructions` receives a `file.uploadReference` without `uploadId`, and `req.payload.collections[collectionSlug].config.upload` is either undefined or has no `handlers` property. The reference is therefore unresolvable: not a staged upload, and no adapter handler to call.","commonSituations":"A storage adapter (S3/GCS/Azure/R2/Vercel Blob) was supposed to register `upload.handlers` but wasn't installed or wired in `payload.config.ts` `plugins`. The adapter plugin is present but its version is too old to register handlers. A custom adapter forgot to set `handlers`. The collection is plain local-storage but the client sent an adapter-style reference.","solutions":["Install and register the storage adapter plugin for the collection in `payload.config.ts` (e.g. `s3Storage({ collections: { media: { ... } } })`).","Verify the adapter version registers `upload.handlers` on the collection config.","If using local storage, make the client use the staged path (request instructions that return `{ uploadReference: { uploadId } }`).","For custom adapters, ensure the plugin sets `collectionConfig.upload.handlers`."],"exampleFix":"// before — collection has upload but no adapter plugin\nexport default buildConfig({\n  collections: [{ slug: 'media', upload: { staticURL: '/media', staticDir: 'media' } }],\n})\n\n// after — register an adapter that provides handlers\nimport { s3Storage } from '@payloadcms/storage-s3'\nexport default buildConfig({\n  collections: [{ slug: 'media', upload: { staticURL: '/media', staticDir: 'media' } }],\n  plugins: [\n    s3Storage({\n      collections: { media: true },\n      bucket: process.env.S3_BUCKET!,\n      config: { endpoint: process.env.S3_ENDPOINT },\n    }),\n  ],\n})","handlingStrategy":"validation","validationCode":"function collectionHasHandlers(config: { upload?: { handlers?: unknown[] } }): boolean {\n  return Array.isArray(config.upload?.handlers) && (config.upload?.handlers?.length ?? 0) > 0\n}\n\nconst col = payload.collections['media']?.config\nif (!collectionHasHandlers(col)) {\n  throw new Error('Register a storage adapter that provides upload.handlers for media')\n}","typeGuard":"function hasHandlers(cfg: unknown): cfg is { upload: { handlers: Array<(req: any, args: any) => unknown> } } {\n  return !!cfg && typeof cfg === 'object' &&\n    !!(cfg as any).upload &&\n    Array.isArray((cfg as any).upload.handlers) &&\n    (cfg as any).upload.handlers.length > 0\n}","tryCatchPattern":"try {\n  await payload.create({ collection: 'media', data, file })\n} catch (err) {\n  if (err instanceof Error && /uploadConfig\\.handlers is not present/i.test(err.message)) {\n    // register the storage adapter plugin, or switch the client to staged uploads\n  } else throw err\n}","preventionTips":["Register the storage adapter plugin in `payload.config.ts` for upload collections.","For local storage, use staged uploads (request `{ uploadReference: { uploadId } }`).","Pin adapter versions that are known to register `handlers`."],"tags":["upload","configuration","storage-adapter","handlers"],"backgroundTag":null,"analyzedSha":"00c58b35c0ed348ddc22daabf467b139727214fd","analyzedAt":"2026-08-12T20:45:03.758Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}