had drifted migration history; repaired migration journal…

Error message

${label} had drifted migration history; repaired migration journal entries from existing schema state.

What it means

At startup, ensureMigrations inspects the database; on 'pending-migrations' it first runs reconcilePendingMigrationHistory, which repairs drizzle migration journal entries from the actual schema state when tables already exist (journal lost, partially written, or out of sync). This warning records which journal entries were repaired, then re-inspects and continues if the DB is now up to date.

Solutions

Usually benign — the repair realigned the journal with the existing schema; verify startup continued to 'already applied'.
If it recurs, diff the schema against `pnpm db:generate` output and ensure exactly one tool applies migrations.
Take a snapshot before restarts for databases with a history of drift.
For DBs with tables but no journal at all, follow the separate 'no migration journal' path (baseline or migrate manually).

Defensive patterns

Strategy: validation

Validate before calling

// Pre-deploy: require a clean migration state against a prod snapshot.
const state = await inspectMigrations(connectionString);
if (state.status === 'needsMigrations') {
  throw new Error(`Migration state needs attention (${state.reason}); run pnpm db:migrate deliberately`);
}

Prevention

Let exactly one tool apply migrations; forbid manual DDL on managed schemas.
Include the drizzle journal table in backup/restore scope.
Alert on any startup 'repaired migration journal' warn — repeated repairs indicate an unmanaged writer.
Snapshot the database before server upgrades so repairs are reversible.

When it happens

Trigger: A database whose schema already contains the 'pending' migrations but whose drizzle journal does not record them — restored snapshots with journal drift, migrations applied by another tool, or a partially damaged journal table.

Common situations: Backup/restore pipelines that lose or truncate the journal; DBs touched by manual DDL or external tooling; copying prod to staging; older Paperclip versions that wrote the journal differently.

Related errors

AI-assisted analysis of paperclipai/paperclip@3f1d897a7c (2026-08-18). Data as JSON: /api/errors/81c3b1d576e481e2. Report an issue: GitHub.

Appendix: source

Thrown at server/src/index.ts:263

  
    const prompt = createInterface({ input: stdin, output: stdout });
    try {
      const answer = (await prompt.question(
        `Apply pending migrations (${formatPendingMigrationSummary(migrations)}) now? (y/N): `,
      )).trim().toLowerCase();
      return answer === "y" || answer === "yes";
    } finally {
      prompt.close();
    }
  }
  
  type EnsureMigrationsOptions = {
    autoApply?: boolean;
  };
  
  async function ensureMigrations(
    connectionString: string,
    label: string,
    opts?: EnsureMigrationsOptions,
  ): Promise<MigrationSummary> {
    const autoApply = opts?.autoApply === true;
    let state = await inspectMigrations(connectionString);
    if (state.status === "needsMigrations" && state.reason === "pending-migrations") {
      const repair = await reconcilePendingMigrationHistory(connectionString);
      if (repair.repairedMigrations.length > 0) {
        logger.warn(
          { repairedMigrations: repair.repairedMigrations },
          `${label} had drifted migration history; repaired migration journal entries from existing schema state.`,
        );
        state = await inspectMigrations(connectionString);
        if (state.status === "upToDate") return "already applied";
      }
    }
    if (state.status === "upToDate") return "already applied";
    if (state.status === "needsMigrations" && state.reason === "no-migration-journal-non-empty-db") {
      logger.warn(

View on GitHub (pinned to 3f1d897a7c)