{"record":{"id":"1a6465a1f8e74a35","repo":"payloadcms/payload","slug":"file-exceeds-the-maxfilesize-byte-upload-limit","errorCode":null,"errorMessage":"File exceeds the ${maxFileSize} byte upload limit.","messagePattern":"File exceeds the (.+?) byte upload limit\\.","errorType":"validation","errorClass":"APIError","httpStatus":400,"severity":"error","filePath":"packages/plugin-mcp/src/mcp/builtin/collections/fileInput.ts","lineNumber":125,"sourceCode":"    }\n\n    file = await getExternalFile({\n      data: {\n        filename: sanitizeFilename(input.name || getURLFilename(url)),\n        url: input.url,\n      } as FileData,\n      req,\n      uploadConfig: {\n        ...uploadConfig,\n        externalFileHeaderFilter: uploadConfig.externalFileHeaderFilter ?? (() => ({})),\n      },\n    })\n    file.mimetype = file.mimetype?.split(';')[0] || 'application/octet-stream'\n    file.size = file.data.length\n  }\n\n  if (maxFileSize !== undefined && Number.isFinite(maxFileSize) && file.size > maxFileSize) {\n    throw new APIError(`File exceeds the ${maxFileSize} byte upload limit.`, 400)\n  }\n\n  return file\n}\n\nfunction decodeBase64({ maxFileSize, value }: { maxFileSize?: number; value: string }): Buffer {\n  const normalized = value.replace(/\\s/g, '')\n\n  if (!/^[a-z0-9+/]*={0,2}$/i.test(normalized) || normalized.length % 4 === 1) {\n    throw new APIError('File data must be valid base64.', 400)\n  }\n\n  if (maxFileSize !== undefined && Number.isFinite(maxFileSize)) {\n    const paddingLength = normalized.endsWith('==') ? 2 : normalized.endsWith('=') ? 1 : 0\n    const decodedSize = Math.floor((normalized.length * 3) / 4) - paddingLength\n\n    if (decodedSize > maxFileSize) {\n      throw new APIError(`File exceeds the ${maxFileSize} byte upload limit.`, 400)","sourceCodeStart":107,"sourceCodeEnd":143,"githubUrl":"https://github.com/payloadcms/payload/blob/00c58b35c0ed348ddc22daabf467b139727214fd/packages/plugin-mcp/src/mcp/builtin/collections/fileInput.ts#L107-L143","documentation":"Thrown as a 400 after a file is materialized (either via base64 decode or externalURL download) when its `file.size` exceeds the global `req.payload.config.upload.limits.fileSize` cap. This is the post-hoc size check — it runs on the final byte count, not on an estimate.","triggerScenarios":"Downloading a remote file via `externalURL` that turns out larger than `config.upload.limits.fileSize`; a base64 payload that decoded to within the estimated limit (see error 368) but the actual `data.length` exceeds it; `maxFileSize` undefined/non-finite lets a huge file through to here only if the limit was added at a different layer.","commonSituations":"`config.upload.limits.fileSize` set lower than the assets users actually upload; remote URL that returns a larger body than its Content-Length header advertised; no client-side size check before the tool call.","solutions":["Raise `config.upload.limits.fileSize` to the intended maximum (in bytes)","Pre-validate file size before calling the tool — for `externalURL`, do a HEAD request and inspect `content-length`","Compress or resize the asset so it fits under the configured limit"],"exampleFix":"// before\nupload: { limits: { fileSize: 1_000_000 } } // 1 MB\n// after\nupload: { limits: { fileSize: 10_000_000 } } // 10 MB","handlingStrategy":"validation","validationCode":"// For externalURL: HEAD the resource and pre-check Content-Length\nconst head = await fetch(url, { method: 'HEAD' })\nconst len = Number(head.headers.get('content-length') ?? 0)\nif (maxFileSize !== undefined && len > maxFileSize) throw new Error(`remote file too large: ${len}`)","typeGuard":null,"tryCatchPattern":"import { APIError } from 'payload'\ntry {\n  await tool.call({ source: 'externalURL', url })\n} catch (e) {\n  if (e instanceof APIError && e.statusCode === 400 && /exceeds the .* byte upload limit/.test(e.message)) {\n    // tell the user the file is too large for the configured cap\n  }\n  throw e\n}","preventionTips":["Set `config.upload.limits.fileSize` to the largest asset you genuinely intend to accept","Do a HEAD request for externalURL sources to pre-validate size before downloading","Show the configured size limit in the upload UI so users resize proactively"],"tags":["mcp","file-upload","size-limit","configuration"],"backgroundTag":null,"analyzedSha":"00c58b35c0ed348ddc22daabf467b139727214fd","analyzedAt":"2026-08-12T20:45:03.758Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}