nodejs/node · error

Illegal utf-8 sequence at Column: %d\n

Error message

Illegal utf-8 sequence at Column: %d\n

What it means

Inside fixu8(), escapesrc walks an already-decoded UTF-8 region with U8_NEXT. If U8_NEXT returns a negative code point (U_INVALID_UTF8 / ill-formed sequence), the input file's bytes are not valid UTF-8 and the tool refuses to emit a \u/\U escape for them. It prints the offending column and the full line for diagnosis.

Source

Thrown at deps/icu-small/source/tools/escapesrc/escapesrc.cpp:288

#endif
      
      // Proceed to decode utf-8
      const uint8_t* s = reinterpret_cast<const uint8_t*>(linestr.c_str());
      int32_t length = linestr.size();
      UChar32 c;
      if(U8_IS_SINGLE((uint8_t)s[i]) && oldIllegal[s[i]]) {
#if (U_CHARSET_FAMILY == U_EBCDIC_FAMILY)
        linestr[pos] = old_byte; // put it back
#endif
        continue; // single code point not previously legal for \u escaping
      }

      // otherwise, convert it to \u / \U
      {
        U8_NEXT(s, i, length, c);
      }
      if(c<0) {
        fprintf(stderr, "Illegal utf-8 sequence at Column: %d\n", static_cast<int>(old_pos));
        fprintf(stderr, "Line: >>%s<<\n", linestr.c_str());
        return true;
      }

      size_t seqLen = (i-pos);

      //printf("U+%04X pos %d [len %d]\n", c, pos, seqLen);fflush(stdout);

      char newSeq[20];
      if( c <= 0xFFFF) {
        snprintf(newSeq, sizeof(newSeq), "\\u%04X", c);
      } else {
        snprintf(newSeq, sizeof(newSeq), "\\U%08X", c);
      }
      linestr.replace(pos, seqLen, newSeq);
      pos += strlen(newSeq) - 1;
    }
  }

View on GitHub (pinned to 1b2de5e052)

Solutions

1. Re-save the offending source file as UTF-8 (without stray bytes) using the editor's encoding command, then rerun escapesrc.
2. Locate the column reported in the message, inspect the bytes, and fix or re-escape the malformed sequence in the literal.
3. Strip any BOM or invalid bytes from the file before feeding it to escapesrc.

Example fix

// before (file is Latin-1, e.g. a non-breaking-space byte 0xA1 inside u8"...")

// after
// re-encode the file as UTF-8 (the byte becomes the proper 2-byte sequence)

// reject non-UTF-8 files before invoking escapesrc
import codecs
with open(path, 'rb') as f:
    data = f.read()
codecs.decode(data, 'utf-8')  # raises UnicodeDecodeError if not valid UTF-8

When it happens

Trigger: A u8"..." literal contains bytes that do not form a valid UTF-8 sequence: truncated multi-byte sequences, illegal lead/continuation byte combinations, or overlong encodings. U8_NEXT sets c<0 in these cases.

Common situations: Source files saved in Latin-1 or another legacy encoding rather than UTF-8; binary garbage injected into a string literal; a BOM or stray byte mid-literal; editor corruption during cross-platform transfer.

Related errors

• Illegal code point U+%X\n
• Cannot do u8'...'\n
• %s: usage: %s infile.cpp outfile.cpp
• Not a 'u'?
• Quote is '%c' - not sure what to do.\n

AI-assisted analysis of nodejs/node@1b2de5e052 (2026-08-13). Data as JSON: /api/errors/e19366b7e2e49bb8. Report an issue: GitHub.