remix-run/remix · error · Error

Unknown migration target: {to}

Error message

Unknown migration target: {to}

What it means

The `to` target option did not match any registered migration. Targets are matched against either the bare id or the full `id_name` string, and zero matches abort the run before anything executes.

Source

Thrown at packages/data-table/src/lib/migrations/runner.ts:77

  }
}

function resolveTargetOption(
  migrations: MigrationDescriptor[],
  to: string | undefined,
): string | undefined {
  if (to === undefined) {
    return undefined
  }

  // Accept either a bare migration id or the full `id_name` directory form and
  // normalize to the bare id so range filtering compares ids consistently.
  let matches = migrations.filter(
    (migration) => migration.id === to || migration.id + '_' + migration.name === to,
  )

  if (matches.length === 0) {
    throw new Error('Unknown migration target: ' + to)
  }

  if (matches.length > 1) {
    throw new Error(
      'Ambiguous migration target "' +
        to +
        '". Matches: ' +
        matches.map((migration) => migration.id + '_' + migration.name).join(', '),
    )
  }

  return matches[0].id
}

async function assertMigrationIntegrity(
  migrations: MigrationDescriptor[],
  journal: MigrationJournalRow[],
  direction: MigrationDirection,

View on GitHub (pinned to 9696913134)

Solutions

1. Use the full `id_name` or the bare numeric id, e.g. `20240101123045_create_users` or `20240101123045`.
2. Print `registry.list()` to confirm available ids and copy the exact target.
3. Trim/normalize CLI-provided target strings before passing them in.

Example fix

// before
await runMigrations(db, { direction: 'up', to: 'create_users' })

// after
await runMigrations(db, { direction: 'up', to: '20240101123045_create_users' })

let valid = registry
  .list()
  .some((m) => m.id === to || m.id + '_' + m.name === to)
if (!valid) throw new Error('unknown --to target: ' + to)

function isKnownTarget(registry: MigrationRegistry, to: string): boolean {
  return registry.list().some((m) => m.id === to || `${m.id}_${m.name}` === to)
}

try {
  await runMigrations(db, { direction: 'up', to })
} catch (error) {
  if (error instanceof Error && error.message.startsWith('Unknown migration target')) {
    console.error('Available:', registry.list().map((m) => `${m.id}_${m.name}`).join('\n'))
  }
  throw error
}

When it happens

Trigger: Calling runMigrations with `{ to: 'create_users' }` (name only, unsupported), a typo'd id, or an id from a branch that isn't in the registry.

Common situations: Passing the migration name without its timestamp id; targeting a migration that exists on another branch or hasn't been generated yet; trailing whitespace from CLI input.

Related errors

• Invalid migration step option. Expected a positive integer.
• Cannot combine "to" and "step" migration options in the same
• expected promise to resolve, but it rejected with: ${stringi
• ${optionName} values must be package names. Received "${pack
• Cannot combine "to" and "step" migration options in the same

AI-assisted analysis of remix-run/remix@9696913134 (2026-08-27). Data as JSON: /api/errors/91018fa34ffe5d68. Report an issue: GitHub.