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 WebAssembly HTML binding's fragment mode (parse with context element): when parse_file_as_document_fragment returns a fatal error, the binding emits the parser error and buffered recoverable errors as diagnostics, then bails with this generic message that surfaces as a JS exception from the wasm module. The diagnostics carry the actual cause. Identical semantics to the Node binding, so the same input fails in both builds.

Source

Thrown at bindings/binding_html_wasm/src/lib.rs:604

                    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. Surface the emitted diagnostics to the user instead of only the generic message
2. Minimize the fragment and retry with the same contextElement to locate the fatal construct
3. Validate/repair input before the call (e.g. with DOMParser) if input is untrusted
4. Report an swc_html issue with the repro if diagnostics contradict the HTML spec

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

try {
  const res = await parse(src, { contextElement });
} catch (e) {
  if (String(e?.message).includes('failed to parse input as document fragment')) {
    return { ok: false, reason: 'invalid-fragment', raw: src };
  }
  throw e;
}

When it happens

Trigger: Calling the wasm fragment parse API (input plus contextElement) with markup that the HTML parser cannot recover from under the given context.

Common situations: In-browser HTML tooling (template linters, sanitizers) feeding fragments with context-sensitive rules broken; passing payloads that are not HTML at all; wasm build used to pre-validate untrusted input without a pre-check.

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 fragment
• failed to parse input as document
• failed to parse input as document
• failed to parse namespace of context element
• Unexpected null character

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