What causes "Upload collection ${upload.collectionSlug} was not found" in payloadcms/payload?

Confirm the collectionSlug in the request body exactly matches a registered upload collection's slug.

payloadcms/payload · error · APIError

Upload collection ${upload.collectionSlug} was not found

Error message

Upload collection ${upload.collectionSlug} was not found

What it means

APIError (HTTP 400) thrown by getUploadInstructions when req.payload.collections[collectionSlug] is missing OR exists but has no config.upload block. Used by the staged-upload flow: the client asks for upload instructions for a collection that is either not registered or not an upload collection.

Source

Thrown at packages/payload/src/uploads/endpoints/uploadInstructions.ts:45

  typeof upload.filesize === 'number' &&
  Number.isSafeInteger(upload.filesize) &&
  upload.filesize >= 0 &&
  'mimeType' in upload &&
  typeof upload.mimeType === 'string'

export const getUploadInstructions = async ({
  overrideAccess = false,
  req,
  ...upload
}: {
  overrideAccess?: boolean
  req: PayloadRequest
} & UploadInstructionsRequest): Promise<UploadInstructions> => {
  const collection = req.payload.collections[upload.collectionSlug]
  const uploadInstructions = collection?.config?.upload?.uploadInstructions

  if (!collection?.config?.upload) {
    throw new APIError(`Upload collection ${upload.collectionSlug} was not found`, 400)
  }

  const filesizeLimit = req.payload.config.upload.limits?.fileSize
  if (filesizeLimit && upload.filesize > filesizeLimit) {
    throw new APIError(
      `Exceeded file size limit. Limit: ${bytesToMB(filesizeLimit).toFixed(2)}MB, got: ${bytesToMB(upload.filesize).toFixed(2)}MB`,
      400,
    )
  }

  await checkFileRestrictions({
    checkFileContents: false,
    collection: collection.config,
    file: {
      name: upload.filename,
      data: Buffer.alloc(0),
      mimetype: upload.mimeType,
      size: upload.filesize,

View on GitHub (pinned to 00c58b35c0)

Solutions

Confirm the collectionSlug in the request body exactly matches a registered upload collection's slug.
Add `upload: { staticDir: '...' }` to the named collection in your Payload config if it should accept uploads.
Sync the client's collection list with the server's after schema changes.
Validate the slug against req.payload.collections before invoking getUploadInstructions from custom code.

Example fix

// client — before
fetch('/api/payload/upload-instructions', { method: 'POST', body: JSON.stringify({ collectionSlug: 'media-files', filename, filesize, mimeType }) })
// after — use the actual upload collection slug registered on the server
fetch('/api/payload/upload-instructions', { method: 'POST', body: JSON.stringify({ collectionSlug: 'media', filename, filesize, mimeType }) })

Defensive patterns

Strategy: type-guard

Validate before calling

const UPLOAD_SLUGS = Object.entries(payload.config.collections)
  .filter(([, c]) => Boolean((c as any).upload))
  .map(([slug]) => slug)
function isValidUploadSlug(slug: string): boolean {
  return UPLOAD_SLUGS.includes(slug)
}
if (!isValidUploadSlug(body.collectionSlug)) throw new Error('Unknown or non-upload collection')

Type guard

const isRegisteredUploadSlug = (slug: string, collections: Record<string, { upload?: unknown }>): boolean =>
  Boolean(collections[slug]?.upload)

Try / catch

try {
  await fetch('/api/payload/upload-instructions', { method: 'POST', body: JSON.stringify(body) })
} catch (e) {
  if (/Upload collection .* was not found/.test(e.message)) alert('Unknown upload collection slug')
}

Prevention

Derive the slug list from server config and share it with the client.
After schema renames, ship a client build that updates the slug list.
Validate the slug against the live collections before the request.
Use TypeScript union types for collection slugs to catch typos at compile time.

When it happens

Trigger: POST /api/payload/upload-instructions with a body whose collectionSlug is unknown to the server, or points to a collection defined without upload. The check `!collection?.config?.upload` covers both the missing-collection and missing-upload-block cases.

Common situations: Client sending a stale/wrong collection slug after a schema rename; frontend typo; collection added without the upload property; requesting staged upload instructions for a non-upload collection; mismatched collection slug between client and server Payload config.

Related errors

AI-assisted analysis of payloadcms/payload@00c58b35c0 (2026-08-12). Data as JSON: /api/errors/3062433946de1853. Report an issue: GitHub.