coder/code-server · error · Error

--vscode-option requires a flag name (got "${entry}")

Error message

--vscode-option requires a flag name (got "${entry}")

What it means

Thrown by parseVscodeOptions in code-server's CLI (src/node/cli.ts) while expanding --vscode-option entries into VS Code server arguments. Each entry must be `flag=value` or a bare `flag`; a leading `--` is stripped and the remainder is split on the first `=`. The error fires when that leaves an empty flag name (an empty entry, an entry starting with `=`, or a bare `--`), which always indicates a typo or quoting bug, so code-server refuses to start rather than silently dropping the option.

Source

Thrown at src/node/cli.ts:952

/**
 * Expand --vscode-option entries into VS Code server arguments.
 *
 * An entry is `flag=value`, or a bare `flag` meaning true.  A leading `--` on
 * the flag is optional, so both spellings people reach for work.  Repeating a
 * flag collects the values into an array, since several VS Code options take
 * one.
 *
 * `true` and `false` become booleans rather than strings.  VS Code tests these
 * flags for truthiness and the string "false" is truthy, so passing it along
 * verbatim would quietly do the opposite of what was asked.
 */
export const parseVscodeOptions = (entries: string[]): Record<string, string | boolean | string[]> => {
  const parsed: Record<string, string | boolean | string[]> = {}

  for (const entry of entries) {
    const [flag, rawValue] = splitOnFirstEquals(entry.replace(/^--/, ""))
    if (!flag) {
      throw new Error(`--vscode-option requires a flag name (got "${entry}")`)
    }

    const value: string | boolean =
      typeof rawValue === "undefined" || rawValue === "true" ? true : rawValue === "false" ? false : rawValue

    const existing = parsed[flag]
    if (typeof existing === "undefined") {
      parsed[flag] = value
    } else if (Array.isArray(existing)) {
      existing.push(String(value))
    } else {
      parsed[flag] = [String(existing), String(value)]
    }
  }

  return parsed
}

View on GitHub (pinned to 88c2b7432e)

Solutions

  1. Read the `(got "...")` part of the message: the entry is empty, starts with `=`, or is just `--`. Rewrite it as `name=value` or a bare flag name (e.g. `--vscode-option enable-sandbox`).
  2. If the entry came from a shell variable, guard against empty expansion, e.g. `${MY_FLAG:+--vscode-option "$MY_FLAG"}`, so the flag is only passed when the variable is set.
  3. If it came from VSCODE_OPTIONS, inspect the variable for stray `=`-leading or empty tokens and fix the spacing/quoting in the environment.
  4. If you build the entries array in code, filter out empty or `=`-prefixed strings before the array reaches code-server.

Example fix

# before — entry has no flag name
code-server --vscode-option =enable-sandbox

# after — bare flag name
code-server --vscode-option enable-sandbox

# before — variable may expand to an empty entry
code-server --vscode-option "$MY_FLAG"

# after — pass the flag only when the variable is set
code-server ${MY_FLAG:+--vscode-option "$MY_FLAG"}
Defensive patterns

Strategy: validation

Validate before calling

const hasFlagName = (entry: string): boolean => {
  const flag = entry.replace(/^--/, "").split("=")[0]
  return flag.length > 0
}

const invalid = entries.filter((e) => !hasFlagName(e))
if (invalid.length > 0) {
  throw new Error(`malformed --vscode-option entries (need name or name=value): ${invalid.join(", ")}`)
}
const parsed = parseVscodeOptions(entries.filter(hasFlagName))

Type guard

const isParsableVscodeOption = (entry: string): entry is string => {
  const flag = entry.replace(/^--/, "").split("=")[0]
  return flag.length > 0
}

Try / catch

try {
  const vscodeOptions = parseVscodeOptions(entries)
} catch (err) {
  if (err instanceof Error && err.message.startsWith("--vscode-option requires a flag name")) {
    // Fail fast with the offending entry surfaced to the operator.
    console.error(`Cannot start: ${err.message}`)
    process.exit(1)
  }
  throw err
}

Prevention

When it happens

Trigger: Running code-server with `--vscode-option ""` (empty quotes), `--vscode-option =value` (value with no flag name), or `--vscode-option --`; or setting the VSCODE_OPTIONS environment variable to a token that is empty or begins with `=` — env tokens are whitespace-split, appended to the vscode-option array (src/node/cli.ts:661-666), and run through the same parser. Any entry that is just `=` also triggers it.

Common situations: Shell variables expanding to empty (`--vscode-option "$FLAG"` with FLAG unset), a stray `=` pasted from docs or a value whose name got deleted, CI pipelines passing VSCODE_OPTIONS with malformed tokens, or scripts building the option array programmatically and including empty strings. The message echoes the offending entry verbatim, so the culprit is visible in the error output.

Understand the failure class

Background: "Unknown argument", "Invalid value", and "must be one of": invalid CLI argument errors explained — this error's family across 35 libraries.

Related errors

AI-assisted analysis of coder/code-server@88c2b7432e (2026-08-21). Data as JSON: /api/errors/51dae764cc0a99d7. Report an issue: GitHub.