remix-run/remix · error · UsageError

Unknown command: db ${command}

Error message

Unknown command: db ${command}

What it means

The db subcommand dispatcher validates the first positional against the known database commands (migrate, and the destructive ones guarded later) and throws when it does not match any of them.

Source

Thrown at packages/cli/src/lib/commands/db.ts:118

      ],
      usage: [
        'remix db wipe --force [options]',
        'remix db migrate [--to <migration>] [options]',
        'remix db rollback [--step <count> | --to <migration>] [--dry-run] [options]',
        'remix db status [options]',
        'remix db seed [options]',
        'remix db reset --force [options]',
      ],
    },
    target,
  )
}

function parseDbCommandArgs(argv: string[]): DatabaseCommandInvocation {
  let [command, ...commandArgv] = argv

  if (!isDatabaseCommand(command)) {
    throw unknownCommand(`db ${command}`)
  }

  if (command === 'migrate') {
    let parsed = parseArgs(
      commandArgv,
      {
        connectionEnv: connectionOption,
        journalTable: journalOption,
        migrations: migrationsOption,
        to: { flag: '--to', type: 'string' },
      },
      { maxPositionals: 0 },
    )
    return { command, ...parsed.options }
  }

  if (command === 'rollback') {
    let parsed = parseArgs(

View on GitHub (pinned to 9696913134)

Solutions

1. Run remix db --help to list supported subcommands in your version
2. Use the correct subcommand (typically remix db migrate)
3. Update @remix-run/cli if docs reference a subcommand your version lacks

Example fix

# before
$ remix db push

# after
$ remix db migrate

const DB_COMMANDS = new Set(['migrate', 'reset', 'wipe']) // mirror isDatabaseCommand

function isKnownDbCommand(cmd?: string): boolean {
  return cmd != null && DB_COMMANDS.has(cmd)
}

function isDatabaseCommand(cmd: string): cmd is 'migrate' | 'reset' | 'wipe' {
  return ['migrate', 'reset', 'wipe'].includes(cmd)
}

try {
  runDbCommand(argv, context)
} catch (error) {
  if (/Unknown command: db/.test(error.message)) printDbHelp()
  else throw error
}

When it happens

Trigger: parseDbCommandArgs sees a command word outside the accepted set, e.g. remix db studio, remix db push, or a typo like remix db migrade.

Common situations: Porting habits from other ORM CLIs (drizzle, prisma) that offer studio/push/generate; typos; CLI versions where a subcommand was renamed or not yet released.

Related errors

• Options --step and --to are mutually exclusive
• throw new AssertionError(options)
• ${matcherName} requires a mock function with a .mock.calls p
• throw new AssertionError({ message, actual, expected, operat
• expect(received).toThrow() requires a function (got ${typeof

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