toeverything/AFFiNE · error · Error

Unknown migration name

Error message

Unknown migration name: ${name}.

What it means

Thrown by RunCommand.runOne(name) when the requested data migration name is not found among the migrations collected from the migrations index (each file exports a name, and lookups are exact string matches).

Solutions

1. List the actual migration names available in your build (src/data/migrations index, or run the run-all command which logs each '✔ <name>' as it executes) and copy the exact name.
2. Match casing and digits exactly — migration names end with a numeric suffix that must be included.
3. Upgrade/downgrade the server image to the version that contains the migration you are targeting.

Example fix

// before
$ node cli.js data run fix-user-avatar  # typo
// after
$ node cli.js data run fix-user-avatar-1700000000

// Verify the name exists before running (server-side helper)
import { collectMigrations } from './commands/run';
const names = collectMigrations().map(m => m.name);
if (!names.includes(name)) {
  console.error(`Unknown migration. Available:\n${names.join('\n')}`);
  process.exit(1);
}

const isValidMigrationName = (name: string): boolean =>
  collectMigrations().some(m => m.name === name);

When it happens

Trigger: Running the 'data run <name>' CLI command with a typo'd, case-mismatched, or nonexistent migration name.

Common situations: Name copied from an old version's migration list that no longer exists in the deployed build; trailing whitespace or wrong casing in the shell argument; referring to a file name instead of the exported migration name.

Related errors

• A migration name is required
• Migration has not been executed.
• A config file path is required
• invalid_app_config_input

AI-assisted analysis of toeverything/AFFiNE@591f874dad (2026-08-18). Data as JSON: /api/errors/d55fc7e315c6016c. Report an issue: GitHub.

Appendix: source

Thrown at packages/backend/server/src/data/commands/run.ts:86

      }

      await this.runMigration(migration);

      done.push(migration);
    }

    this.logger.log(`Done ${done.length} migrations`);
    done.forEach(migration => {
      this.logger.log(`  ✔ ${migration.name}`);
    });
  }

  async runOne(name: string) {
    const migrations = collectMigrations();
    const migration = migrations.find(m => m.name === name);

    if (!migration) {
      throw new Error(`Unknown migration name: ${name}.`);
    }
    const exists = await this.db.dataMigration.count({
      where: {
        name: migration.name,
      },
    });

    if (exists) return;

    await this.runMigration(migration);
  }

  async admitLegacyContextBlobs(): Promise<void> {
    const tables = await this.db.$queryRaw<
      Array<{
        contexts: string | null;
        sessions: string | null;
        blobs: string | null;

View on GitHub (pinned to 591f874dad)