Troubleshooting Common Issues

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• src/index.ts
• src/index.spec.ts
• test/sizzle.spec.ts
• test/advanced-selectors.spec.ts
• package.json

This guide addresses common technical hurdles and unexpected behaviors encountered when using cheerio-select. As a wrapper around css-select that adds jQuery-style positional pseudo-selectors (like :first, :eq, and :gt), issues typically arise from syntax errors, context mismatches, or incorrect assumptions about how these additional selectors interact with standard CSS logic.

Understanding the internal routing between "plain" CSS selectors and "filtered" (positional) selectors is critical for debugging performance or unexpected result sets.

Sources: README.md:1-12, src/index.ts:252-276

Selector Syntax and Parser Errors

The most frequent issues involve malformed selector strings. The cheerio-select engine relies on css-what for parsing; providing invalid CSS or jQuery syntax will cause the selector engine to throw errors.

Broken Selectors

Certain characters and sequences are explicitly unsupported or require specific escaping. For example, unbalanced brackets, parentheses, or trailing commas will trigger a failure.

Issue	Example	Corrective Action
Unbalanced Brackets	[id=val	Ensure all [ have a matching ].
Trailing Commas	div,	Remove trailing commas as they imply an empty selector.
Malformed Nth-child	:nth-child(asdf)	Use valid formulas like 2n+1, even, or odd.
Unquoted Brackets	input[name=foo[bar]]	Quote attribute values containing brackets: input[name="foo[bar]"].

Sources: test/sizzle.spec.ts:161-193, src/index.spec.ts:18-22

Escaping Special Characters

Identifiers (IDs or Classes) containing special characters such as dots, colons, or backslashes must be escaped twice: once for the JavaScript string and once for the CSS selector syntax.

// To find <div id="foo:bar">
select("#foo\\:bar", document); 

// To find <div class="test.foo[5]bar">
select(".test\\.foo\\[5\\]bar", document);

Sources: test/sizzle.spec.ts:208-220, test/sizzle.spec.ts:269-275

Positional Selector Behavior

jQuery-style positional selectors (:first, :last, :eq, :nth, :gt, :lt, :even, :odd) operate differently than standard CSS pseudo-classes. They filter the entire set of previously matched elements rather than operating relative to their parent.

Indexing and Limits

Positional selectors are zero-indexed. If an invalid index (e.g., a non-numeric string) is provided to :eq(), :lt(), or :gt(), the engine will return an empty set rather than throwing an error.

The diagram shows how positional selectors introduce a filtering step after the initial element retrieval.

Sources: src/index.ts:89-122, src/index.spec.ts:20-22

Performance and Optimization

The select function optimizes queries by grouping selectors. "Plain" selectors are queried in a single pass, while those containing positional filters are processed sequentially. If a selector starts with a positional pseudo, cheerio-select may bypass deep traversal and only look at immediate children or the provided context to improve speed.

Sources: src/index.ts:252-276, src/index.ts:289-315

Context and Root Mismatches

Issues often occur when the search root or context is not what the user expects, leading to empty results or elements found outside the intended scope.

The :scope Pseudo-selector

When using filter() or providing a specific context to select(), the :scope pseudo-class refers to the elements currently being evaluated. A common mistake is assuming a descendant combinator (like div p) will match when the div is actually the context element itself. In such cases, :scope p or a relative selector is required.

Sources: src/index.ts:192-210, src/index.spec.ts:60-61

Traversal-First Queries

Selectors starting with combinators (e.g., + .class or ~ div) require a specific element as the starting point. If the root is a Document rather than an Element, these traversals may fail to find siblings.

This diagram illustrates how cheerio-select handles traversal-first queries by expanding the search context to include siblings via prepareContext.

Sources: src/index.ts:402-411, src/index.spec.ts:44-48

XML vs HTML Mode

Behavioral differences exist between HTML and XML parsing, specifically regarding case sensitivity and namespace handling.

• Case Sensitivity: In standard HTML, tag names are case-insensitive. In xmlMode: true, they are case-sensitive.
• Namespaces: Selecting namespaced elements (e.g., soap:Envelope) requires escaping the colon in the selector: soap\\:Envelope.
• Attributes: Certain attributes like class may behave differently in XML fixtures compared to standard HTML DOMs.

Sources: test/sizzle.spec.ts:143-160, test/tools/sizzle-testinit.ts:83-86

Summary of Troubleshooting Steps

1. Validate Syntax: Ensure brackets are balanced and attribute values with special characters are quoted.
2. Verify Indices: Check that :eq(index) uses a valid numeric index within the range of the result set.
3. Check Escaping: Use double backslashes (\\) for CSS special characters in JavaScript strings.
4. Confirm Context: If results are empty, verify if the root element is part of the match or if a relative selector/:scope is needed.
5. Audit XML Mode: If working with XML, ensure xmlMode: true is set in options and check for case sensitivity.

Sources: src/index.ts:28-40, test/sizzle.spec.ts:31-40