← Back to docs

Error Codes

Parse errors that JustHTML can detect and report.

Collecting Errors

By default, JustHTML silently recovers from errors (like browsers do). To collect errors:

from justhtml import JustHTML

doc = JustHTML("<p>Hello", collect_errors=True)
for error in doc.errors:
    print(f"{error.line}:{error.column} - {error.category}:{error.code}")

doc.errors is ordered by source position (line, column), with unknown positions (if any) appearing last.

Error Categories

Each error has a category field:

• tokenizer: lexical/tokenization errors
• treebuilder: tree construction (structure) errors
• security: sanitizer findings (only when you opt in via unsafe_handling="collect")

Strict Mode

To reject malformed HTML entirely:

from justhtml import JustHTML, StrictModeError

try:
    doc = JustHTML("<p>Hello", strict=True)
except StrictModeError as e:
    print(e)  # Shows source location

In strict mode, JustHTML raises on the earliest error by source position.

Error Locations (Line/Column)

JustHTML reports a source location for each parse error as a best-effort pointer to where the parser detected the problem in the input stream.

• Coordinates are 1-based: the first character in the input is (line=1, column=1).
• Tokenizer-detected character errors (for example unexpected-null-character) should point at the exact offending character within the input, even if that character is emitted as part of a larger run of text.
• Tree-builder (structure) errors are associated with the token that triggered the error.
  • In practice this usually means the error points at (or near) the triggering token location, because the tree builder operates on tokens rather than individual characters.
  • When available, JustHTML will highlight the full triggering tag range.
• EOF-related errors point to the end-of-input position where the parser realized it could not continue.

This means error locations are not universally “at the beginning” or “at the end” of a token: character-level errors point at the character, while token-level (tree builder) errors generally point at the triggering token’s start.

Node Locations (Optional)

Sometimes you want a source location for a node, not just for parse errors.

For performance reasons, node locations are disabled by default. To enable them, pass track_node_locations=True when parsing:

from justhtml import JustHTML

doc = JustHTML("<p>hi</p>", track_node_locations=True)
p = doc.query("p")[0]

print(p.origin_location)  # (1, 1)
print(p.origin_line)      # 1
print(p.origin_col)       # 1
print(p.origin_offset)    # 0 (0-indexed)

Each node exposes best-effort origin metadata:

• origin_location -> (line, col) | None (both 1-indexed)
• origin_line -> int | None (1-indexed)
• origin_col -> int | None (1-indexed)
• origin_offset -> int | None (0-indexed offset into the input)

Notes:

• If track_node_locations=False (default), these are typically None.
• Locations are best-effort. When the tree builder creates or moves nodes as part of error recovery, the reported origin is the location of the token that created the node (or the closest available source position).
• Enabling node tracking adds overhead. If you only need error locations, prefer collect_errors=True / strict=True.

Example: Reporting missing includes

import sys
from pathlib import Path

from justhtml import JustHTML


with open(sys.argv[1]) as f:
    html = f.read()

doc = JustHTML(html, track_node_locations=True)
for include_node in doc.query("x-include"):
    src = include_node.attrs.get("src", "")
    if not Path(src).exists():
        line, col = include_node.origin_location or (0, 0)
        print(f"Missing include source: {src} ({sys.argv[1]}:{line}.{col})")

Tokenizer Errors

Errors detected during tokenization (lexical analysis).

DOCTYPE Errors

Comment Errors

Tag Errors

Attribute Errors

Script Errors

CDATA Errors

Character Reference Errors

Other Tokenizer Errors

Tree Builder Errors

Errors detected during tree construction.

DOCTYPE Errors

Unexpected Tag Errors

EOF Errors

Invalid Character Errors

Table Errors

Frameset Errors

After-Body Errors

Column Group / Template Table Context Errors

Fragment Context Errors

Head/Body Context Errors

Foreign Content Errors

Select Errors

Miscellaneous Errors

Security Errors

Errors reported by the sanitizer when you opt in via unsafe_handling="collect".