{"record":{"id":"d6e3f5c348b63f7f","repo":"payloadcms/payload","slug":"e-message","errorCode":null,"errorMessage":"${e.message}","messagePattern":"\\$\\{e\\.message\\}","errorType":"http","errorClass":"APIError","httpStatus":500,"severity":"error","filePath":"packages/payload/src/config/orderable/index.ts","lineNumber":232,"sourceCode":"      // We cannot update all documents in a single operation with `payload.update`,\n      // because they would all end up with the same order key (`a0`).\n      try {\n        for (const doc of docs) {\n          await req.payload.update({\n            id: doc.id,\n            collection: collection.slug,\n            data: {\n              // no data needed since the order hooks will handle this\n            },\n            depth: 0,\n            req,\n          })\n          await commitTransaction(req)\n        }\n      } catch (e) {\n        await killTransaction(req)\n        if (e instanceof Error) {\n          throw new APIError(e.message, httpStatus.INTERNAL_SERVER_ERROR)\n        }\n      }\n\n      return new Response(JSON.stringify({ message: 'initial migration', success: true }), {\n        headers: { 'Content-Type': 'application/json' },\n        status: 200,\n      })\n    }\n\n    if (\n      typeof target !== 'object' ||\n      typeof target.id === 'undefined' ||\n      typeof target.key !== 'string'\n    ) {\n      return new Response(JSON.stringify({ error: 'target must be an object with id' }), {\n        headers: { 'Content-Type': 'application/json' },\n        status: 400,\n      })","sourceCodeStart":214,"sourceCodeEnd":250,"githubUrl":"https://github.com/payloadcms/payload/blob/00c58b35c0ed348ddc22daabf467b139727214fd/packages/payload/src/config/orderable/index.ts#L214-L250","documentation":"Thrown during the one-time orderable migration: when `orderable` is first enabled on a collection that already has documents, Payload back-fills the ordering key for each existing doc by calling `payload.update` inside a transaction. If any per-doc update throws an `Error`, the transaction is killed and the message is re-thrown as an `APIError` with HTTP 500.","triggerScenarios":"Enabling `orderable: true` on a collection that already contains rows, where one of those rows fails validation during the back-fill (e.g. a required field now missing, a beforeChange hook rejecting, a unique constraint hit).","commonSituations":"Adding orderable to a long-lived collection with legacy data that violates current field constraints; a `beforeChange`/`beforeValidate` hook that throws on legacy docs; concurrent edits during the migration.","solutions":["Inspect the wrapped `e.message` (surfaced via the APIError) to find the underlying field/hook error.","Fix or clean the offending documents so they pass validation, then retry the reorder request.","Temporarily disable offending hooks or loosen validation, run the migration, then restore them."],"exampleFix":"// before: enabling orderable on a collection with invalid legacy docs\ncollections: [{ slug: 'items', orderable: true, fields: [{ name: 'title', required: true }] }]\n// after: backfill missing titles first, then enable orderable\nawait payload.update({ collection: 'items', where: { title: { exists: false } }, data: { title: 'Untitled' } })","handlingStrategy":"try-catch","validationCode":"// Before enabling orderable, ensure existing docs pass current validation\nconst { docs } = await payload.find({ collection: 'items', limit: 0, depth: 0, req })\nfor (const d of docs) {\n  await payload.update({ collection: 'items', id: d.id, data: {}, req }).catch((e) => {\n    throw new Error(`Doc ${d.id} would fail orderable migration: ${e.message}`)\n  })\n}","typeGuard":null,"tryCatchPattern":"try {\n  await fetch('/api/items/reorder', { method: 'POST', body: JSON.stringify({ target: { key: null } }) })\n} catch (err) {\n  if (err instanceof APIError && err.status === 500) {\n    // initial orderable migration failed — fix the offending docs, then retry\n  }\n  throw err\n}","preventionTips":["Backfill/validate legacy docs before enabling `orderable`.","Keep `beforeChange` hooks tolerant of legacy data during the migration window.","Run the first reorder against a staging copy of the data."],"tags":["orderable","migration","collections","transaction","hooks"],"backgroundTag":null,"analyzedSha":"00c58b35c0ed348ddc22daabf467b139727214fd","analyzedAt":"2026-08-12T20:45:03.758Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}