pydantic/monty · error · TypeError

invalid mode: '${char}'

Error message

invalid mode: '${char}'

What it means

The mode string contained a character that is not one of r/w/a/x/b/t/+. canonicalFileMode validates mode character-by-character and throws a TypeError naming the offending character for anything unrecognized.

Source

Thrown at crates/monty-js/ts/types.ts:143

  let action: string | undefined
  let binary = false
  let text = false
  for (const char of mode) {
    if (char === 'r' || char === 'w' || char === 'a') {
      if (action !== undefined) throw new TypeError('must have exactly one of create/read/write/append mode')
      action = char
    } else if (char === 'x') {
      throw new TypeError('exclusive creation mode is not supported')
    } else if (char === 'b') {
      if (binary) throw new TypeError('invalid mode: binary mode specified twice')
      binary = true
    } else if (char === 't') {
      if (text) throw new TypeError('invalid mode: text mode specified twice')
      text = true
    } else if (char === '+') {
      throw new TypeError("update modes ('+') are not yet supported")
    } else {
      throw new TypeError(`invalid mode: '${char}'`)
    }
  }
  if (binary && text) throw new TypeError("can't have text and binary mode at once")
  if (action === undefined) {
    throw new TypeError('Must have exactly one of create/read/write/append mode and at most one plus')
  }
  return `${action}${binary ? 'b' : ''}`
}

/** Validates that a file position can cross the JavaScript boundary exactly. */
export function validateFilePosition(position: unknown): asserts position is number {
  if (typeof position !== 'number' || !Number.isSafeInteger(position) || position < 0) {
    throw new TypeError('MontyFileHandle position must be a non-negative safe integer')
  }
}

View on GitHub (pinned to adc986b362)

Solutions

  1. Check the quoted character in the message and remove it from the mode string
  2. Use only characters from {r,w,a,b,t} (and note '+' and 'x' are separately rejected)
  3. Trim/normalize the mode string before passing: `mode.trim().toLowerCase()`

Example fix

// before
const fh = new MontyFileHandle(path, ' r')
// after
const fh = new MontyFileHandle(path, 'r')
Defensive patterns

Strategy: validation

Validate before calling

if (typeof mode !== 'string' || !/^[rwabt+]*$/.test(mode)) throw new Error('mode contains unsupported characters')

Type guard

function isWellFormedMode(mode) { return typeof mode === 'string' && /^[rwabt+]*$/.test(mode) }

Try / catch

try { fh = new MontyFileHandle(path, mode) } catch (e) { if (e instanceof TypeError && e.message.startsWith("invalid mode: '")) throw new Error(`bad mode config: ${mode}`) ; throw e }

Prevention

When it happens

Trigger: Passing modes with stray characters such as 'r w' (space), 're' (typo), 'R' (uppercase), or numerically-indexed characters from a bad config to MontyFileHandle's constructor or pushFileHandle.

Common situations: Typos in mode strings ('wt!' vs 'w'), uppercasing the whole mode ('W'), whitespace from template strings, or locale/formatting mistakes when building the mode dynamically.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

AI-assisted analysis of pydantic/monty@adc986b362 (2026-09-13). Data as JSON: /api/errors/4d54f2626d94cbdc. Report an issue: GitHub.