{"record":{"id":"4478cdf410b6da37","repo":"payloadcms/payload","slug":"id-was-not-specified","errorCode":null,"errorMessage":"ID was not specified","messagePattern":"ID was not specified","errorType":"exception","errorClass":"APIError","httpStatus":400,"severity":"error","filePath":"packages/payload/src/utilities/getRequestEntity.ts","lineNumber":47,"sourceCode":"    disableSanitize?: T\n    optionalID?: boolean\n  } = {},\n): {\n  collection: Collection\n  id: T extends true ? string : number | string\n} => {\n  const collection = getRequestCollection(req)\n  const id = req.routeParams?.id\n\n  if (typeof id !== 'string') {\n    if (optionalID) {\n      return {\n        id: undefined!,\n        collection,\n      }\n    }\n\n    throw new APIError(`ID was not specified`, 400)\n  }\n\n  if (disableSanitize === true) {\n    return {\n      id,\n      collection,\n    }\n  }\n\n  let sanitizedID: number | string = id\n\n  // If default db ID type is a number, we should sanitize\n  let shouldSanitize = Boolean(req.payload.db.defaultIDType === 'number')\n\n  // UNLESS the customIDType for this collection is text.... then we leave it\n  if (shouldSanitize && collection.customIDType === 'text') {\n    shouldSanitize = false\n  }","sourceCodeStart":29,"sourceCodeEnd":65,"githubUrl":"https://github.com/payloadcms/payload/blob/00c58b35c0ed348ddc22daabf467b139727214fd/packages/payload/src/utilities/getRequestEntity.ts#L29-L65","documentation":"Thrown by `getRequestCollectionWithID` when `req.routeParams.id` is absent or not a string and `optionalID` is not set. This guard ensures single-document routes (GET/PATCH/DELETE by ID) always receive a document identifier in the URL.","triggerScenarios":"A request reaches a single-document endpoint (e.g. `/api/:collection/:id`) but the route did not capture an `id` param, or an internal call invoked `getRequestCollectionWithID` without `optionalID: true` and no id present.","commonSituations":"The route pattern is missing the `:id` segment; a URL rewrite dropped the ID; the client called `/api/collection` (list endpoint) instead of `/api/collection/:id`; a custom route forwards to Payload without populating `routeParams.id`; programmatic code constructs a request object without the id param.","solutions":["Ensure the request URL includes the document ID segment (e.g. `/api/posts/42`).","If calling programmatically, set `req.routeParams = { collection: 'posts', id: '42' }`.","If the ID is legitimately optional (e.g. a combined create/find handler), pass `optionalID: true` to `getRequestCollectionWithID`.","Verify the client targets the correct endpoint shape (list vs single-document).","If using a custom ID type, confirm the value is a string in routeParams."],"exampleFix":"// before\nawait fetch('/api/posts') // intended GET by ID, but no :id in URL\n\n// after\nawait fetch('/api/posts/42')","handlingStrategy":"validation","validationCode":"// Ensure the ID is present in the route params before resolution\nif (typeof req.routeParams?.id !== 'string') {\n  throw new Error('Missing document ID in route params')\n}","typeGuard":"const hasIdParam = (req) => typeof req.routeParams?.id === 'string'","tryCatchPattern":"try {\n  const { id, collection } = getRequestCollectionWithID(req)\n} catch (e) {\n  if (e instanceof APIError && e.message === 'ID was not specified') {\n    // add :id to the URL or pass optionalID: true if appropriate\n  } else throw e\n}","preventionTips":["Always include the document ID in single-document endpoint URLs.","Use optionalID: true when a handler serves both list and single-document operations.","Set req.routeParams.id on synthetic requests.","Use the Local API with explicit id arguments for programmatic operations."],"tags":["routing","collection","id","request"],"backgroundTag":null,"analyzedSha":"00c58b35c0ed348ddc22daabf467b139727214fd","analyzedAt":"2026-08-12T20:45:03.758Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}