upstash/context7 · error · Error

Invalid TOML Unicode code point U+${hex}

Error message

Invalid TOML Unicode code point U+${hex}

What it means

A \u/\U escape had valid hex digits but the resulting code point is invalid: greater than U+10FFFF or inside the surrogate range U+D800–U+DFFF, which Unicode forbids as scalar values.

Source

Thrown at packages/cli/src/setup/toml-editor.ts:64

    }

    const escape = source[index++];
    if (Object.hasOwn(TOML_BASIC_ESCAPES, escape)) {
      value += TOML_BASIC_ESCAPES[escape];
      continue;
    }
    if (escape !== "u" && escape !== "U") {
      throw new Error(`Unsupported TOML escape \\${escape}`);
    }

    const width = escape === "u" ? 4 : 8;
    const hex = source.slice(index, index + width);
    if (!new RegExp(`^[0-9A-Fa-f]{${width}}$`).test(hex)) {
      throw new Error(`Invalid TOML Unicode escape \\${escape}${hex}`);
    }
    const codePoint = Number.parseInt(hex, 16);
    if (codePoint > 0x10ffff || (codePoint >= 0xd800 && codePoint <= 0xdfff)) {
      throw new Error(`Invalid TOML Unicode code point U+${hex}`);
    }
    value += String.fromCodePoint(codePoint);
    index += width;
  }
  throw new Error("Unterminated TOML basic string in MCP args");
}

function parseTomlLiteralString(source: string, start: number): TomlStringToken {
  const endQuote = source.indexOf("'", start + 1);
  if (endQuote === -1) throw new Error("Unterminated TOML literal string in MCP args");
  const value = source.slice(start + 1, endQuote);
  if (value.includes("\n") || value.includes("\r")) {
    throw new Error("Multiline strings are not supported in MCP args");
  }
  return { value, start, end: endQuote + 1 };
}

function parseTomlStringArray(

View on GitHub (pinned to edc9eeb77b)

Solutions

  1. Replace surrogate pairs with the single combined code point (\U0001F600 instead of \uD83D\ude00)
  2. Keep code points ≤ U+10FFFF and outside D800–DFFF
  3. Avoid emojis/symbols in machine args unless correctly escaped

Example fix

// before
args = ["\uD83D\ude00"]
// after
args = ["\U0001F600"]
Defensive patterns

Strategy: validation

Validate before calling

for (const m of s.matchAll(/\\u([0-9A-Fa-f]{4})|\\U([0-9A-Fa-f]{8})/g)) {
  const cp = parseInt(m[1] ?? m[2], 16);
  if (cp > 0x10ffff || (cp >= 0xd800 && cp <= 0xdfff)) throw new Error('surrogate/OOB code point');
}

Type guard

function isValidScalarEscape(hex: string): boolean {
  const cp = parseInt(hex, 16);
  return cp <= 0x10ffff && !(cp >= 0xd800 && cp <= 0xdfff);
}

Try / catch

catch (e) { if (/code point/.test(e.message)) { /* replace surrogate pairs with combined \U escape */ } throw e; }

Prevention

When it happens

Trigger: args containing \UD800AAAA, \uDFFF0000, or \U00110000+.

Common situations: Copy-pasting surrogate pair halves from JSON \uD83D\ude00-style escapes (TOML requires the combined code point, e.g. \U0001F600); typos in 8-digit escapes.

Related errors

AI-assisted analysis of upstash/context7@edc9eeb77b (2026-08-28). Data as JSON: /api/errors/a2437cd5f7e7479b. Report an issue: GitHub.