remix-run/remix · error · UsageError

Unknown command: assets ${command}

Error message

Unknown command: assets ${command}

What it means

The assets subcommand only accepts 'list' (default) and 'inspect'; any other positional command word is rejected as unknown before execution.

Source

Thrown at packages/cli/src/lib/commands/assets.ts:75

      examples: [
        'remix assets',
        'remix assets inspect /assets/app/actions/public/entry.ts',
        'remix assets inspect app/actions/public/entry.ts',
      ],
      usage: ['remix assets', 'remix assets inspect <url-or-file>'],
    },
    target,
  )
}

type AssetsCommandInvocation = { command: 'list' } | { command: 'inspect'; input: string }

function parseAssetsCommandArgs(argv: string[]): AssetsCommandInvocation {
  let parsed = parseArgs(argv, {}, { maxPositionals: 2 })
  let [command, input] = parsed.positionals

  if (command === undefined) return { command: 'list' }
  if (command !== 'inspect') throw unknownCommand(`assets ${command}`)
  if (input === undefined) {
    throw invalidOptionValue('`remix assets inspect` requires a URL or file path.')
  }
  return { command, input }
}

function formatAssetList(assets: readonly AssetDetails[], rootDir: string): string {
  if (assets.length === 0) return 'No assets.\n'
  return `${assets
    .map((asset) => `${asset.url} -> ${formatFilePath(asset.filePath, rootDir)}`)
    .join('\n')}\n`
}

function formatAssetDetails(details: AssetDetails, rootDir: string): string {
  let lines = [`Status: ${details.status}`]
  if (details.url !== undefined) lines.push(`URL: ${details.url}`)
  if (details.filePath !== undefined) {
    lines.push(`File: ${formatFilePath(details.filePath, rootDir)}`)

View on GitHub (pinned to 9696913134)

Solutions

1. Use remix assets list or remix assets inspect <url-or-path>
2. Check remix assets --help for the supported subcommands in your CLI version
3. Update the CLI if following current docs that document a subcommand your version lacks

Example fix

# before
$ remix assets sync

# after
$ remix assets list

const ASSETS_COMMANDS = new Set(['list', 'inspect'])

function isKnownAssetsCommand(cmd?: string): boolean {
  return cmd === undefined || ASSETS_COMMANDS.has(cmd!)
}

function isAssetsCommand(cmd: string): cmd is 'list' | 'inspect' {
  return cmd === 'list' || cmd === 'inspect'
}

try {
  runAssetsCommand(argv, context)
} catch (error) {
  if (/Unknown command: assets/.test(error.message)) printAssetsHelp()
  else throw error
}

When it happens

Trigger: parseAssetsCommandArgs finds a first positional that is not undefined and not 'inspect', e.g. remix assets build, remix assets sync, or a typo like remix assets inspeect.

Common situations: Assuming the assets command mirrors other subcommands (build/sync); tab-completion or muscle-memory typos; older/newer CLI versions with different subcommand sets.

Related errors

• `remix assets inspect` requires a URL or file path.
• RMX_UNEXPECTED_ARGUMENT
• --config requires a value.
• Asset configuration is missing from remix.json.
• Unknown command: db ${command}

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