payloadcms/payload · error · APIError

Invalid upload collection.

Error message

Invalid upload collection.

What it means

Thrown when the collection slug resolved for a staged upload either is empty or does not correspond to a collection with an `upload` config. Payload checks `req.payload.collections[collectionSlug]?.config.upload` and requires both a slug and a truthy upload config.

Source

Thrown at packages/payload/src/utilities/addDataAndFileToRequest.ts:78

      }

      if (!req.file && fields?.file && typeof fields?.file === 'string') {
        let uploadedFile: UploadInstructions['file']
        try {
          uploadedFile = JSON.parse(fields.file)
        } catch {
          throw new APIError('A file name is required.', 400)
        }
        const collectionSlug =
          typeof req.routeParams?.collection === 'string'
            ? req.routeParams.collection
            : uploadedFile.collectionSlug
        const uploadConfig = collectionSlug
          ? req.payload.collections[collectionSlug]?.config.upload
          : undefined

        if (!collectionSlug || !uploadConfig) {
          throw new APIError('Invalid upload collection.', 400)
        }

        req.file = await getFileFromUploadInstructions({
          collectionSlug,
          file: uploadedFile,
          req,
        })
      }
    }
  }
}

View on GitHub (pinned to 00c58b35c0)

Solutions

1. Ensure the target collection has `upload` enabled in its config.
2. Verify the `collectionSlug` in the `file` instruction matches a registered upload collection slug exactly.
3. If the request is to a collection-specific route, confirm the route param resolves correctly; otherwise include `collectionSlug` in the instruction JSON.
4. Check for slug casing / naming mismatches between client and server config.

Example fix

// before -- collection has no upload config
const mediaCollection = { slug: 'media', fields: [...] }
// client sends file instruction with collectionSlug: 'media'

// after
const mediaCollection = {
  slug: 'media',
  upload: { staticDir: 'media', imageSizes: [...] },
  fields: [...],
}

// Verify the collection exists and has upload enabled before sending
const slug = 'media'
const collection = payloadConfig.collections.find(c => c.slug === slug)
if (!collection?.upload) {
  throw new Error(`Collection '${slug}' is not an upload collection`)
}

const isUploadCollection = (c) => !!c && c.upload !== undefined

try {
  await fetch(url, { method: 'POST', body: formData })
} catch (e) {
  if (e instanceof APIError && e.message === 'Invalid upload collection.') {
    // verify collectionSlug is correct and upload is enabled in config
  } else throw e
}

When it happens

Trigger: The `file` JSON object `collectionSlug` is missing/empty AND the request route does not provide a collection param; or the resolved slug refers to a collection that has no `upload` property (i.e. it is not an upload-enabled collection).

Common situations: Sending a staged-upload `file` instruction for a collection that is not configured with `upload: { ... }`; the `collectionSlug` in the instruction JSON is misspelled or refers to a non-upload collection; the request is hitting a generic route without a collection route param and the instruction omits `collectionSlug`.

Related errors

• Field ${field.label} has invalid relationship '${relationshi
• File type '${file.mimetype}' is not allowed.
• Upload collection ${upload.collectionSlug} was not found
• Invalid template given
• Invalid database type given. Valid types are: ${Object.value

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