swc-project/swc · error · swc_xml_parser::error::Error

UnexpectedCharacter

UnexpectedCharacter

Error message

Unexpected character, only whitespace character allowed

What it means

The XML start phase (before the root element) permits only whitespace character data. When a Character token with a non-whitespace value arrives there, `UnexpectedCharacter` is recorded at the token's span (crates/swc_xml_parser/src/parser/mod.rs:281) and the text is otherwise ignored — parsing continues waiting for the root element. This is the standard 'content before root element' well-formedness violation.

Source

Thrown at crates/swc_xml_parser/src/parser/mod.rs:281

                    self.phase = Phase::EndPhase;
                }
                Token::Comment { .. } => {
                    self.append_comment_to_doc(token_and_info)?;
                }
                Token::ProcessingInstruction { .. } => {
                    self.append_processing_instruction_to_doc(token_and_info)?;
                }
                Token::Cdata { .. } => {
                    self.errors.push(Error::new(
                        token_and_info.span,
                        ErrorKind::UnexpectedTokenInStartPhase,
                    ));

                    self.append_cdata_to_doc(token_and_info)?;
                }
                Token::Character { value, .. } => {
                    if !is_whitespace(*value) {
                        self.errors.push(Error::new(
                            token_and_info.span,
                            ErrorKind::UnexpectedCharacter,
                        ));
                    }
                }
                Token::Eof => {
                    self.errors.push(Error::new(
                        token_and_info.span,
                        ErrorKind::UnexpectedEofInStartPhase,
                    ));

                    self.process_token(token_and_info, Some(Phase::EndPhase))?;
                }
                Token::Doctype { .. } => {
                    let document_type = self.create_document_type_for_token(token_and_info);

                    self.append_node(self.document.as_ref().unwrap(), document_type);
                }

View on GitHub (pinned to 5176682b65)

Solutions

1. Strip leading non-whitespace text before the root element in the producer
2. Locate what prepends the text (echo/log statement, banner, BOM) and remove it
3. Split mixed content: parse only the substring starting at the first `<` that begins the root element
4. Decode input as UTF-8 and drop a leading U+FEFF BOM before parsing

Example fix

<!-- before -->
OK: <root><a/></root>
<!-- after -->
<root><a/></root>

// Verify only whitespace precedes the root element
function assertPrologIsWhitespace(xml: string): void {
  const rootIdx = xml.search(/<[a-zA-Z_:]/);
  const prolog = (rootIdx === -1 ? xml : xml.slice(0, rootIdx))
    .replace(/<\?[\s\S]*?\?>|<!--([\s\S]*?)-->|<!DOCTYPE[^>]*>/g, '');
  if (/\S/.test(prolog)) throw new Error('non-whitespace text before root element');
}

for err in parser.take_errors() {
    if matches!(err.kind, ErrorKind::UnexpectedCharacter) {
        // text before root was ignored; find and remove it at the producer
    }
}

When it happens

Trigger: Parsing input such as `hello<root/>` or `123<root/>` — any non-whitespace text before the first start tag reaches the Character branch of the start-phase handler.

Common situations: Log lines or banners prepended to XML responses; concatenation bugs that join plain text with an XML body; a BOM decoded as a character by a non-UTF-8-aware reader; response envelopes that prefix payloads with status text.

Related errors

• UnexpectedTokenInStartPhase
• Cannot use import.meta outside a module
• Assignment to constant variable.
• attempted to get private field on non-instance
• The requested module '{specifier}' does not provide an expor

AI-assisted analysis of swc-project/swc@5176682b65 (2026-08-17). Data as JSON: /api/errors/42643fe8fa886294. Report an issue: GitHub.