{"record":{"id":"f29d7513e28bca53","repo":"payloadcms/payload","slug":"no-previous-migration-schema-file-found-a-prior-m","errorCode":null,"errorMessage":"No previous migration schema file found! A prior migration from v2 is required to migrate to v3.","messagePattern":"No previous migration schema file found! A prior migration from v2 is required to migrate to v3\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"packages/drizzle/src/postgres/predefinedMigrations/v2-v3/index.ts","lineNumber":64,"sourceCode":" * @param req\n */\nexport const migratePostgresV2toV3 = async ({ debug, payload, req }: Args) => {\n  const adapter = payload.db as unknown as BasePostgresAdapter\n  const dir = payload.db.migrationDir\n\n  // get the drizzle migrateUpSQL from drizzle using the last schema\n  const { generateDrizzleJson, generateMigration, upSnapshot } = adapter.requireDrizzleKit()\n  const drizzleJsonAfter = generateDrizzleJson(adapter.schema) as DrizzleSnapshotJSON\n\n  // Get the previous migration snapshot\n  const previousSnapshot = fs\n    .readdirSync(dir)\n    .filter((file) => file.endsWith('.json') && !file.endsWith('relationships_v2_v3.json'))\n    .sort()\n    .reverse()?.[0]\n\n  if (!previousSnapshot) {\n    throw new Error(\n      `No previous migration schema file found! A prior migration from v2 is required to migrate to v3.`,\n    )\n  }\n\n  let drizzleJsonBefore = JSON.parse(\n    fs.readFileSync(`${dir}/${previousSnapshot}`, 'utf8'),\n  ) as DrizzleSnapshotJSON\n\n  if (upSnapshot && drizzleJsonBefore.version < drizzleJsonAfter.version) {\n    drizzleJsonBefore = upSnapshot(drizzleJsonBefore)\n  }\n\n  const generatedSQL = await generateMigration(drizzleJsonBefore, drizzleJsonAfter)\n\n  if (!generatedSQL.length) {\n    payload.logger.info(`No schema changes needed.`)\n    process.exit(0)\n  }","sourceCodeStart":46,"sourceCodeEnd":82,"githubUrl":"https://github.com/payloadcms/payload/blob/00c58b35c0ed348ddc22daabf467b139727214fd/packages/drizzle/src/postgres/predefinedMigrations/v2-v3/index.ts#L46-L82","documentation":"Thrown by the Postgres v2→v3 migration when no prior Drizzle snapshot JSON file is found in the migration directory. The v2→v3 migration diffs the previous snapshot against the current schema to generate the column moves (relationships/uploads out of the join table), so without a baseline snapshot there is nothing to diff and the migration cannot run.","triggerScenarios":"Invoking `migratePostgresV2toV3` in a project whose migration directory contains no `.json` snapshot files (other than `relationships_v2_v3.json`, which is explicitly excluded), e.g. a project that never generated v2 migrations, or whose migration directory is empty/misconfigured.","commonSituations":"Attempting v2→v3 on a fresh project with no migration history; migration directory cleared or pointing at the wrong path; project that used `push`/auto-sync instead of generated migrations; the only JSON present is the v2-v3 relationships file.","solutions":["Ensure the project has a prior v2-era migration with its generated `.json` snapshot in the migration directory before running the v3 upgrade.","Generate a baseline migration on the v2 codebase first (`payload migrate:create`), commit the snapshot, then run the v2→v3 migration.","Confirm `payload.db.migrationDir` resolves to the directory containing the historical snapshots."],"exampleFix":"// before: migrationDir has no *.json snapshot -> throws\n// after: on the v2 branch, generate the baseline first\n//   payload migrate:create baseline\n// commit the produced .json snapshot, then run the v2->v3 migration","handlingStrategy":"validation","validationCode":"import fs from 'fs'\nconst snapshot = fs.readdirSync(payload.db.migrationDir)\n  .filter(f => f.endsWith('.json') && !f.endsWith('relationships_v2_v3.json'))\n  .sort().reverse()[0]\nif (!snapshot) {\n  throw new Error('No v2 snapshot found; generate baseline migrations on the v2 branch first.')\n}\nawait migratePostgresV2toV3({ payload })","typeGuard":"null","tryCatchPattern":"try {\n  await migratePostgresV2toV3({ payload })\n} catch (err) {\n  if (/No previous migration schema file found/.test(String(err?.message))) {\n    payload.logger.error('Generate a v2 baseline migration snapshot before upgrading.')\n  }\n  throw err\n}","preventionTips":["Generate and commit migration snapshots on each Payload version.","Keep the migration directory intact across version upgrades.","Run v2->v3 only after a valid v2 migration baseline exists."],"tags":["migrations","drizzle","v2-v3-upgrade","snapshot"],"backgroundTag":null,"analyzedSha":"00c58b35c0ed348ddc22daabf467b139727214fd","analyzedAt":"2026-08-12T20:45:03.758Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}