upstash/context7 · error · Error

Invalid TOML Unicode escape \\${escape}${hex}

Error message

Invalid TOML Unicode escape \\${escape}${hex}

What it means

A \u or \U unicode escape was found in a double-quoted string, but the characters following it are not the required 4 (for \u) or 8 (for \U) hex digits. Example: \u12 or \U00GG0000.

Source

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

    }
    if (char !== "\\") {
      value += char;
      continue;
    }

    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");
  }

View on GitHub (pinned to edc9eeb77b)

Solutions

  1. Provide exactly 4 hex digits after \u and 8 after \U
  2. Use only 0-9, A-F, a-f in the escape
  3. If you meant a literal backslash+u, double the backslash or use a single-quoted string

Example fix

// before
args = ["\u12"]
// after
args = ["\u0012"]
Defensive patterns

Strategy: validation

Validate before calling

const re = /\\u([0-9A-Fa-f]{0,3})(?![0-9A-Fa-f])|\\U([0-9A-Fa-f]{0,7})(?![0-9A-Fa-f])/g;
if (re.test(s)) throw new Error('Short/invalid unicode escape');

Type guard

function hasValidUnicodeEscapes(s: string): boolean {
  return !/\\u(?![0-9A-Fa-f]{4})(?!.)/.test(s.replace(/\\u[0-9A-Fa-f]{4}/g, ''))
    && !/\\U(?![0-9A-Fa-f]{8})/.test(s);
}

Try / catch

catch (e) { if (/Invalid TOML Unicode escape/.test(e.message)) { /* pad \u to 4 / \U to 8 hex digits */ } throw e; }

Prevention

When it happens

Trigger: args = ["\u12"] (too few digits), \uZZZZ (non-hex letters), or a \U truncated by the end of line/string.

Common situations: Emacs/JS-style \u escapes with fewer than 4 digits; hand-shortening unicode escapes; a \U escape accidentally cut off when editing the line.

Related errors

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