remix-run/remix · error · Error

Cannot combine "to" and "step" migration options in the same

Error message

Cannot combine "to" and "step" migration options in the same run

What it means

The remix-db CLI rollback command accepts either --to <target> (roll back to a specific migration) or --step <n> (roll back n steps), but not both. runRemixDb rejects the combination before touching the database because the two options imply conflicting rollback endpoints.

Source

Thrown at packages/data-table/src/cli.ts:109

      options.to === undefined
        ? { journalTable: options.journalTable }
        : { to: options.to, journalTable: options.journalTable }
    let result = await options.db.migrate(options.migrations, migrateOptions)

    if (result.applied.length === 0) {
      console.log('no pending migrations')
    }

    for (let entry of result.applied) {
      console.log('applied ' + entry.id + '_' + entry.name)
    }

    return 0
  }

  if (options.command === 'rollback') {
    if (options.to !== undefined && options.step !== undefined) {
      throw new Error('Cannot combine "to" and "step" migration options in the same run')
    }

    let result =
      options.to === undefined
        ? await options.db.migrate(options.migrations, {
            direction: 'down',
            step: options.step ?? 1,
            dryRun: options.dryRun,
            journalTable: options.journalTable,
          })
        : await options.db.migrate(options.migrations, {
            direction: 'down',
            to: options.to,
            dryRun: options.dryRun,
            journalTable: options.journalTable,
          })

    if (result.reverted.length === 0) {

View on GitHub (pinned to 9696913134)

Solutions

1. Choose one: use `--to <migration-id>` for an absolute target or `--step <n>` for a relative count.
2. For 'roll back everything', prefer `--to 0` or the reset command rather than combining options.

Example fix

# before
remix-db rollback --to 0003 --step 2

# after
remix-db rollback --step 2

if (options.to !== undefined && options.step !== undefined) {
  throw new Error('Pass either --to or --step, not both')
}

When it happens

Trigger: Running `remix-db rollback --to 0003 --step 2` or constructing options with both `to` and `step` set for the rollback command programmatically.

Common situations: Copy-pasting a previous rollback command and appending flags; CI scripts that pass both options defensively; misunderstanding that `to` is an absolute target while `step` is relative.

Related errors

• expected promise to resolve, but it rejected with: ${stringi
• ${optionName} values must be package names. Received "${pack
• Invalid migration step option. Expected a positive integer.
• throw new AssertionError(options)
• ${matcherName} requires a mock function with a .mock.calls p

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