{"record":{"id":"ce44a3d8d86c86ef","repo":"payloadcms/payload","slug":"migration-migration-name-not-found-locally-ce44a3","errorCode":null,"errorMessage":"Migration ${migration.name} not found locally.","messagePattern":"Migration (.+?) not found locally\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/payload/src/database/migrations/migrateDown.ts","lineNumber":32,"sourceCode":"  const { existingMigrations, latestBatch } = await getMigrations({\n    payload,\n  })\n\n  if (!existingMigrations?.length) {\n    payload.logger.info({ msg: 'No migrations to rollback.' })\n    return\n  }\n\n  payload.logger.info({\n    msg: `Rolling back batch ${latestBatch} consisting of ${existingMigrations.length} migration(s).`,\n  })\n\n  const latestBatchMigrations = existingMigrations.filter(({ batch }) => batch === latestBatch)\n\n  for (const migration of latestBatchMigrations) {\n    const migrationFile = migrationFiles.find((m) => m.name === migration.name)\n    if (!migrationFile) {\n      throw new Error(`Migration ${migration.name} not found locally.`)\n    }\n\n    const start = Date.now()\n    const req = await createLocalReq({}, payload)\n\n    try {\n      payload.logger.info({ msg: `Migrating down: ${migrationFile.name}` })\n      await initTransaction(req)\n      const session = payload.db.sessions?.[await req.transactionID!]\n      await migrationFile.down({ payload, req, session })\n      payload.logger.info({\n        msg: `Migrated down:  ${migrationFile.name} (${Date.now() - start}ms)`,\n      })\n      // Waiting for implementation here\n      await payload.delete({\n        id: migration.id!,\n        collection: 'payload-migrations',\n        req,","sourceCodeStart":14,"sourceCodeEnd":50,"githubUrl":"https://github.com/payloadcms/payload/blob/00c58b35c0ed348ddc22daabf467b139727214fd/packages/payload/src/database/migrations/migrateDown.ts#L14-L50","documentation":"Thrown by `migrateDown` (`payload migrate:rollback`) when the `payload-migrations` table records a migration whose name has no matching file in the local migrations directory. Rollback must execute the migration's `down` function, which only exists in the file — so a missing file aborts the rollback. Typically the migration file was deleted, renamed, or the deployed code is behind the DB.","triggerScenarios":"Running `payload migrate:rollback` after deleting a migration file from `src/migrations`; deploying code that no longer ships an older migration that the DB still records; renaming a migration file without re-syncing the DB.","commonSituations":"Squashing/cleaning up migration files mid-project; CI/CD deploy that pruned old migrations; switching branches where the migration set differs.","solutions":["Restore the missing migration file from version control so its `down()` is available.","If the rollback is intentionally impossible, manually remove the row from the `payload-migrations` collection/table.","Keep migration files immutable once applied — never delete applied migrations."],"exampleFix":"# before: migration file deleted, rollback fails\npayload migrate:rollback\n# after: restore the file, then rollback\ngit checkout HEAD -- src/migrations/2024_01_01_init.ts\npayload migrate:rollback","handlingStrategy":"validation","validationCode":"import { readdir } from 'fs/promises'\nconst local = new Set((await readdir('./src/migrations')).map(stripExt))\nconst recorded = await payload.find({ collection: 'payload-migrations', limit: 0 })\nconst missing = recorded.docs.filter((m) => !local.has(m.name))\nif (missing.length) throw new Error(`Missing local migration files: ${missing.map((m) => m.name).join(', ')}`)","typeGuard":null,"tryCatchPattern":"try {\n  await payload.db.migrateDown()\n} catch (err) {\n  if (/not found locally/.test((err as Error).message)) {\n    // restore the file from git or remove the stray DB row, then retry\n  }\n  throw err\n}","preventionTips":["Never delete applied migration files — keep them in version control.","Before rollback, ensure every DB-recorded migration has a local file.","If intentionally dropping a migration, also delete its `payload-migrations` row."],"tags":["database","migrations","cli","rollback","drift"],"backgroundTag":null,"analyzedSha":"00c58b35c0ed348ddc22daabf467b139727214fd","analyzedAt":"2026-08-12T20:45:03.758Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}