coder/code-server · error · Error

-- requires a value

Error message

--${key} requires a value

What it means

code-server's CLI argument parser (parse, called from args) throws this when a non-boolean, non-OptionalString option is supplied without a value. A flag's value is taken from a `--flag=value` suffix or from the next argv token, but only if that token does not itself start with a dash. When neither yields a value, the parser cannot populate the option and aborts with `--<key> requires a value`.

Solutions

1. Supply the missing value, either space-separated (`--bind-addr 0.0.0.0:8080`) or with equals (`--bind-addr=0.0.0.0:8080`).
2. If the value legitimately starts with a dash or is negative, use the `--flag=value` form, which bypasses the next-token dash check.
3. Quote variables in shell scripts (`--bind-addr "$ADDR"`) and verify the variable is non-empty (e.g. `${ADDR:?ADDR is not set}`) so an unset env var can't leave the flag valueless.
4. Run `code-server --help` to confirm the option actually takes a value; boolean options never need one.

Example fix

// before (ADDR unset, value lost)
code-server --bind-addr $ADDR

// after (fail fast or default)
code-server --bind-addr "${ADDR:-0.0.0.0:8080}"

function assertFlagHasValue(argv: string[], flag: string) {
  const idx = argv.findIndex((a) => a === flag || a.startsWith(flag + "="))
  if (idx === -1) return true // flag not used
  if (argv[idx].includes("=")) return argv[idx].split("=")[1] !== ""
  return idx + 1 < argv.length && argv[idx + 1] !== "" && !argv[idx + 1].startsWith("-")
}
// if (!assertFlagHasValue(process.argv, "--bind-addr")) { /* fix invocation */ }

function hasFlagValue<T extends Record<string, unknown>>(args: T, key: keyof T): args is T & Record<keyof T, string> {
  return typeof args[key] === "string" && (args[key] as string).length > 0
}

try {
  const args = await args(process.argv)
  // use args
} catch (err) {
  if (err instanceof Error && err.message.endsWith("requires a value")) {
    const key = err.message.match(/^--(.+) requires a value$/)?.[1]
    console.error(`The --${key} option needs a value. Try: --${key}=<value>. Use --help for details.`)
    process.exit(1)
  }
  throw err
}

When it happens

Trigger: Passing a value-requiring flag with nothing after it (e.g. `code-server --bind-addr` as the last argument); passing a value that begins with a dash so it is mistaken for another option (e.g. `--cert-key -abc`); using a negative number directly after a flag like `--idle-timeout-seconds -5`, since argv[i+1].startsWith('-') makes the value undefined.

Common situations: Truncated or hand-edited shell scripts and systemd unit files where a variable holding the value expands to empty (e.g. `--bind-addr $ADDR` with ADDR unset); users copying boolean-style usage onto value options; typos where a later flag appears where the value was expected (e.g. forgetting the equals sign: `--bind-addr --port 8080`).

Understand the failure class

Background: "no subcommand specified" and "... is required": CLI errors when a required argument is missing — this error's family across 13 libraries.

Related errors

• --idle-timeout-seconds must be greater than 60 seconds.
• Cannot open socket paths
• --cert-key is missing
• entry is required
• filePath is required

AI-assisted analysis of coder/code-server@8a7bf87a4d (2026-09-22). Data as JSON: /api/errors/b6c786dfccc62e1d. Report an issue: GitHub.

Appendix: source

Thrown at src/node/cli.ts:448

      }

      const option = options[key]
      if (option.type === "boolean") {
        ;(args[key] as boolean) = true
        continue
      }

      // Might already have a value if it was the --long=value format.
      if (typeof value === "undefined") {
        // A value is only valid if it doesn't look like an option.
        value = argv[i + 1] && !argv[i + 1].startsWith("-") ? argv[++i] : undefined
      }

      if (!value && option.type === OptionalString) {
        ;(args[key] as OptionalString) = new OptionalString(value)
        continue
      } else if (!value) {
        throw error(`--${key} requires a value`)
      }

      if (key === "idle-timeout-seconds" && Number(value) <= 60) {
        throw new Error("--idle-timeout-seconds must be greater than 60 seconds.")
      }

      if (option.type === OptionalString && value === "false") {
        continue
      }

      if (option.path) {
        value = path.resolve(value)
      }

      switch (option.type) {
        case "string":
          ;(args[key] as string) = value
          break

View on GitHub (pinned to 8a7bf87a4d)