What causes "Unexpected type of selector" in cheeriojs/cheerio?

Ensure the selector is a string: cheerio(String(sel)) or validate before calling

cheeriojs/cheerio · error · TypeError

Unexpected type of selector

Error message

Unexpected type of selector

What it means

When the cheerio function is called with selector-like arguments (no existing Cheerio/element instance), the selector must be a string. Passing any other type (number, object, null, function) as the selector throws this TypeError.

Source

Thrown at src/load.ts:225

        typeof selector === 'string' && isHtml(selector)
          ? // $(<html>)
            parse(selector, options, false, null).children
          : isNode(selector)
            ? // $(dom)
              [selector]
            : Array.isArray(selector)
              ? // $([dom])
                selector
              : undefined;

      const instance = new LoadedCheerio(elements, rootInstance, options);

      if (elements) {
        return instance as Cheerio<Result>;
      }

      if (typeof selector !== 'string') {
        throw new TypeError('Unexpected type of selector');
      }

      // We know that our selector is a string now.
      let search = selector;

      const searchContext: Cheerio<AnyNode> | undefined = context
        ? // If we don't have a context, maybe we have a root, from loading
          typeof context === 'string'
          ? isHtml(context)
            ? // $('li', '<ul>...</ul>')
              new LoadedCheerio<Document>(
                [parse(context, options, false, null)],
                rootInstance,
                options,
              )
            : // $('li', 'ul')
              ((search = `${context} ${search}` as S), rootInstance)
          : isCheerio<AnyNode>(context)

View on GitHub (pinned to a1be131f9b)

Solutions

Ensure the selector is a string: cheerio(String(sel)) or validate before calling
If selecting by node, pass an actual parsed node or Cheerio collection, not a plain object
Check the variable is defined and log its type before invoking cheerio()

Example fix

// before
const $ = cheerio(selectorFromInput); // may be a number/object
// after
if (typeof selectorFromInput !== 'string') {
  throw new Error(`Invalid selector: ${typeof selectorFromInput}`);
}
const $ = cheerio(selectorFromInput);

Defensive patterns

Strategy: type-guard

Validate before calling

if (typeof selector !== 'string' && !isNodeLike(selector)) {
  throw new Error(`Invalid selector type: ${typeof selector}`);
}
const $ = cheerio(selector);

Type guard

function isSelector(sel: unknown): sel is string {
  return typeof sel === 'string';
}
// use: if (isSelector(sel)) cheerio(sel);

Try / catch

try { const $ = cheerio(sel); } catch (e) { if (e instanceof TypeError && /Unexpected type of selector/.test(e.message)) { console.warn('bad selector', sel); return; } throw e; }

Prevention

Validate user-supplied selectors are strings
Pass parsed nodes/Cheerio collections, not plain objects
Check variables are defined before calling cheerio()

When it happens

Trigger: Calling cheerio(123), cheerio({}), cheerio(null) with a context/elements argument combination that routes into the selector branch, or cheerio(someVar) where someVar is not a string, element, or Cheerio instance.

Common situations: Passing a parsed JSON object or a DOM-like object that isn't a recognized node; passing numbers from user input; variables that are undefined due to typos or unresolved imports; mixing up argument order.

Related errors

AI-assisted analysis of cheeriojs/cheerio@a1be131f9b (2026-08-28). Data as JSON: /api/errors/3b88d4e8d556bdc6. Report an issue: GitHub.