pnpm/pnpm · error · PnpmError

RUNTIME_UNKNOWN_SUBCOMMAND

RUNTIME_UNKNOWN_SUBCOMMAND

Error message

Unknown subcommand: ${params[0]}

What it means

The runtime handler's switch only recognizes `set`; any other first parameter hits the default branch and throws RUNTIME_UNKNOWN_SUBCOMMAND with the offending value interpolated into the message plus a help hint. Unlike the no-subcommand case, this names what you passed, making typos obvious. The supported surface is intentionally small while the command is young.

Source

Thrown at pnpm11/engine/runtime/commands/src/runtime/runtime.ts:94

      'pnpm runtime set deno 2 -g',
      'pnpm runtime set bun latest -g',
    ],
  })
}

export async function handler (opts: RuntimeCommandOptions, params: string[]): Promise<void> {
  if (params.length === 0) {
    throw new PnpmError('RUNTIME_NO_SUBCOMMAND', 'Please specify the subcommand', {
      hint: help(),
    })
  }
  switch (params[0]) {
    case 'set': {
      runtimeSet(opts, params.slice(1))
      return
    }
    default: {
      throw new PnpmError('RUNTIME_UNKNOWN_SUBCOMMAND', `Unknown subcommand: ${params[0]}`, {
        hint: help(),
      })
    }
  }
}

function runtimeSet (opts: RuntimeCommandOptions, params: string[]): void {
  const runtimeName = params[0]?.trim()
  if (!runtimeName) {
    throw new PnpmError('MISSING_RUNTIME_NAME', '"pnpm runtime set <name> <version>" requires a runtime name (e.g. node, deno, bun)')
  }
  // The runtime name is interpolated into an `add` selector, so reject
  // anything that isn't a known runtime before it can be misread as a
  // comma-separated package list or a local path by the install pipeline.
  if (!isRuntimeAlias(runtimeName)) {
    throw new PnpmError('INVALID_RUNTIME_NAME', `"${runtimeName}" is not a supported runtime. Supported runtimes are: ${RUNTIME_NAMES.join(', ')}`)
  }

View on GitHub (pinned to 5b11d3a15b)

Solutions

1. Use the only implemented subcommand: `pnpm runtime set <name> <version>`.
2. For listing, keep using `pnpm env list` until runtime grows a list command.
3. Read the included hint for the exact accepted forms.

Example fix

# before
pnpm runtime list   # ERR_PNPM_RUNTIME_UNKNOWN_SUBCOMMAND: Unknown subcommand: list
# after
pnpm runtime set node 22 -g
pnpm env list   # listing still lives here

const KNOWN_RUNTIME_SUBCOMMANDS = new Set(['set'])
export function isKnownRuntimeSubcommand (sub: string): boolean {
  return KNOWN_RUNTIME_SUBCOMMANDS.has(sub)
}

const RUNTIME_SUBCOMMANDS = ['set'] as const
type RuntimeSubcommand = typeof RUNTIME_SUBCOMMANDS[number]
function isRuntimeSubcommand (value: string): value is RuntimeSubcommand {
  return (RUNTIME_SUBCOMMANDS as readonly string[]).includes(value)
}

When it happens

Trigger: `pnpm runtime list`, `pnpm runtime use`, `pnpm runtime remove` — anything besides `set`; also tab-completed guesses imported from the env/nvm vocabulary.

Common situations: Assuming runtime mirrors env's subcommands; migrating scripts from `pnpm env` and forgetting to rename the verb; typos like `st`.

Related errors

• ENV_UNKNOWN_SUBCOMMAND
• RUNTIME_NO_SUBCOMMAND
• MISSING_RUNTIME_NAME
• MISSING_PACKAGE_NAME
• TOO_MANY_PARAMS

AI-assisted analysis of pnpm/pnpm@5b11d3a15b (2026-08-16). Data as JSON: /api/errors/4588f2de1cfb0033. Report an issue: GitHub.