{"record":{"id":"7354187e6cc728ff","repo":"payloadcms/payload","slug":"migration-migration-name-not-found-locally-735418","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/migrateRefresh.ts","lineNumber":34,"sourceCode":"\n  const { existingMigrations } = await getMigrations({\n    payload,\n  })\n\n  const req = await createLocalReq({}, payload)\n\n  if (existingMigrations?.length) {\n    payload.logger.info({\n      msg: `Rolling back all ${existingMigrations.length} migration(s).`,\n    })\n    // Reverse order of migrations to rollback\n    existingMigrations.reverse()\n\n    for (const migration of existingMigrations) {\n      try {\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        payload.logger.info({ msg: `Migrating down: ${migration.name}` })\n        const start = Date.now()\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:  ${migration.name} (${Date.now() - start}ms)`,\n        })\n        await payload.delete({\n          collection: 'payload-migrations',\n          req,\n          where: {\n            name: {\n              equals: migration.name,\n            },\n          },","sourceCodeStart":16,"sourceCodeEnd":52,"githubUrl":"https://github.com/payloadcms/payload/blob/00c58b35c0ed348ddc22daabf467b139727214fd/packages/payload/src/database/migrations/migrateRefresh.ts#L16-L52","documentation":"Thrown by `migrateRefresh` (`payload migrate:fresh`-style refresh: roll back all then re-apply) when a migration recorded in the DB has no corresponding local file. Identical root cause to error 172 but triggered during a full refresh: the loop reverses every recorded migration and needs each one's `down` function. A single missing file stops the whole refresh.","triggerScenarios":"Running `payload migrate:refresh`/`fresh` with a migration in the DB whose file was removed; branch switching that drops a previously-applied migration file; a deploy that pruned older migration files.","commonSituations":"Resetting a staging DB after migration cleanup; onboarding scripts that run refresh against a DB seeded by an older code version.","solutions":["Restore all missing migration files from git so every recorded migration has a `down()`.","If some are intentionally gone, delete their rows from `payload-migrations` before refreshing.","Avoid deleting applied migration files; archive instead."],"exampleFix":"# before: refresh fails on missing file\npayload migrate:fresh\n# after: restore files, then refresh\ngit checkout HEAD -- src/migrations/\npayload migrate:fresh","handlingStrategy":"validation","validationCode":"import { readdir } from 'fs/promises'\nconst local = new Set((await readdir('./src/migrations')).map(stripExt))\nconst { docs } = await payload.find({ collection: 'payload-migrations', limit: 0 })\nconst missing = docs.filter((m) => !local.has(m.name))\nif (missing.length) throw new Error(`Cannot refresh; missing files: ${missing.map((m) => m.name).join(', ')}`)","typeGuard":null,"tryCatchPattern":"try {\n  await payload.db.migrateRefresh()\n} catch (err) {\n  if (/not found locally/.test((err as Error).message)) {\n    // restore all missing files or purge their DB rows before re-running\n  }\n  throw err\n}","preventionTips":["Keep the full set of applied migrations in the repo.","Validate file/DB sync before running migrate:fresh.","Do not prune old migration files in deployed artifacts."],"tags":["database","migrations","cli","refresh","drift"],"backgroundTag":null,"analyzedSha":"00c58b35c0ed348ddc22daabf467b139727214fd","analyzedAt":"2026-08-12T20:45:03.758Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}