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

failed to parse input as document fragment

Error message

failed to parse input as document fragment

What it means

The Node HTML binding's fragment mode (parse with a context element) calls parse_file_as_document_fragment; if that returns a fatal error, the binding first emits the parser error plus every accumulated recoverable error as diagnostics and then bails with this generic message. The actionable detail lives in the emitted diagnostics, not in this string. It means the fragment was invalid in a way the error-tolerant HTML parser could not recover from.

Source

Thrown at bindings/binding_html_node/src/lib.rs:560

                    form_element.as_ref(),
                    swc_html::parser::parser::ParserConfig {
                        scripting_enabled,
                        iframe_srcdoc: opts.iframe_srcdoc,
                        ..Default::default()
                    },
                    &mut errors,
                );

                let document_fragment = match document_fragment {
                    Ok(v) => v,
                    Err(err) => {
                        err.to_diagnostics(handler).emit();

                        for err in errors {
                            err.to_diagnostics(handler).emit();
                        }

                        bail!("failed to parse input as document fragment")
                    }
                };

                (
                    DocumentOrDocumentFragment::DocumentFragment(document_fragment),
                    Some(context_element),
                )
            } else {
                let document = parse_file_as_document(
                    &fm,
                    swc_html::parser::parser::ParserConfig {
                        scripting_enabled,
                        iframe_srcdoc: opts.iframe_srcdoc,
                        ..Default::default()
                    },
                    &mut errors,
                );

View on GitHub (pinned to 5176682b65)

Solutions

1. Read the diagnostics emitted immediately before the bail - they carry file, line, column and the real parser message
2. Reproduce with a minimal fragment and the same contextElement to isolate the offending markup
3. Drop the contextElement and try document mode to see whether the fragment context itself is the problem
4. If diagnostics flag valid HTML, file an swc_html issue with the minimal repro and both parser errors

function preflightFragment(input, contextElement) {
  if (typeof input !== 'string' || input.length === 0) {
    throw new TypeError('fragment input must be a non-empty string');
  }
  // cheap DOM-based check for untrusted input
  if (typeof DOMParser !== 'undefined') {
    const doc = new DOMParser().parseFromString(input, 'text/html');
    if (doc.querySelector('parsererror')) return false;
  }
  return true;
}

try {
  const res = parseSync(src, { contextElement });
} catch (e) {
  if (String(e?.message).includes('failed to parse input as document fragment')) {
    // the diagnostics emitted to stderr carry the real positions; collect them if the binding exposes an errors return
    return { ok: false, reason: 'invalid-fragment', raw: src };
  }
  throw e;
}

When it happens

Trigger: Calling the fragment parse path (input plus contextElement) with markup that fatally violates parsing rules for the given context, e.g. content that is illegal inside the chosen context element or structurally broken input the parser cannot recover from.

Common situations: Parsing template fragments with the wrong context element (e.g. table-fragment rules under a div context); passing empty or non-HTML payloads; regressions in swc_html parser versions that turn previously-recovered errors into fatal ones.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• failed to parse input as document
• failed to parse input as document fragment
• failed to parse namespace of context element
• failed to parse input as document
• Unexpected null character

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