{"record":{"id":"76a2cf6b28c9f065","repo":"microsoft/playwright","slug":"failed-to-find-element-matching-selector-select","errorCode":null,"errorMessage":"Failed to find element matching selector \"${selector}\"","messagePattern":"Failed to find element matching selector \"(.+?)\"","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/playwright-core/src/server/frames.ts","lineNumber":913,"sourceCode":"    });\n    return scope ? scope._context.raceAgainstContextDestroyed(promise) : promise;\n  }\n\n  async dispatchEvent(progress: Progress, selector: string, type: string, eventInit: Object = {}, options: types.QueryOnSelectorOptions, scope?: dom.ElementHandle): Promise<void> {\n    await this._waitForFunctionOnSelector(progress, selector, (injectedScript, element, data) => {\n      injectedScript.dispatchEvent(element, data.type, data.eventInit);\n      return { result: undefined };\n    }, { type, eventInit }, { mainWorld: true, ...options }, scope);\n  }\n\n  async evalOnSelector(progress: Progress, selector: string, strict: boolean, expression: string, isFunction: boolean | undefined, arg: any, scope?: dom.ElementHandle): Promise<any> {\n    return progress.race(this._evalOnSelector(selector, strict, expression, isFunction, arg, scope));\n  }\n\n  private async _evalOnSelector(selector: string, strict: boolean, expression: string, isFunction: boolean | undefined, arg: any, scope?: dom.ElementHandle): Promise<any> {\n    const handle = await this.selectors.query(selector, { strict }, scope);\n    if (!handle)\n      throw new Error(`Failed to find element matching selector \"${selector}\"`);\n    const result = await handle.internalEvaluateExpression(expression, { isFunction }, arg);\n    handle.dispose();\n    return result;\n  }\n\n  async evalOnSelectorAll(progress: Progress, selector: string, expression: string, isFunction: boolean | undefined, arg: any, scope?: dom.ElementHandle): Promise<any> {\n    return progress.race(this._evalOnSelectorAll(selector, expression, isFunction, arg, scope));\n  }\n\n  private async _evalOnSelectorAll(selector: string, expression: string, isFunction: boolean | undefined, arg: any, scope?: dom.ElementHandle): Promise<any> {\n    const arrayHandle = await this.selectors.queryArrayInMainWorld(selector, scope);\n    const result = await arrayHandle.internalEvaluateExpression(expression, { isFunction }, arg);\n    arrayHandle.dispose();\n    return result;\n  }\n\n  async querySelectorAll(progress: Progress, selector: string): Promise<dom.ElementHandle<Element>[]> {\n    return progress.race(this.selectors.queryAll(selector));","sourceCodeStart":895,"sourceCodeEnd":931,"githubUrl":"https://github.com/microsoft/playwright/blob/c8fc3bf8d31542d59b4d4d9eaab1df93ff541dc6/packages/playwright-core/src/server/frames.ts#L895-L931","documentation":"evalOnSelector (the single-element variant behind page.$eval / locator.evaluate on the first match) requires exactly one element. After querying the selector with no match it throws 'Failed to find element matching selector \"...\"'.","triggerScenarios":"Calling page.\\$eval / elementHandle.\\$eval / locator-based single-element evaluation on a selector that matches zero elements at query time (within the timeout, since this internal path has no built-in wait).","commonSituations":"Selector typos; element not yet rendered; dynamic content that appears after an async delay; shadow DOM the selector does not pierce; iframe content where the selector is run in the wrong frame; strict vs non-strict mismatch.","solutions":["Use a Locator and waitFor() before evaluating so the element is present.","Fix the selector (try getByRole/getByTestId) and verify with page.locator(sel).count().","Ensure you are querying the right frame (use frameLocator for iframes).","Use \\$$eval (all-matches) if you genuinely want to operate on zero-or-many."],"exampleFix":"// before\nawait page.$eval('#missing', el => el.textContent); // throws\n// after\nconst loc = page.locator('#x');\nawait loc.waitFor();\nconst text = await loc.evaluate(el => el.textContent);","handlingStrategy":"validation","validationCode":"// Ensure a match exists before the single-element eval\nif (await page.locator(sel).count() === 0) throw new Error('no match: ' + sel);\nawait page.$eval(sel, fn);","typeGuard":"async function hasMatch(page: any, sel: string): Promise<boolean> {\n  return (await page.locator(sel).count()) > 0;\n}","tryCatchPattern":"try {\n  await page.$eval(sel, fn);\n} catch (e) {\n  if (e instanceof Error && /Failed to find element matching selector/.test(e.message)) { /* wait + retry */ }\n  else throw e;\n}","preventionTips":["Prefer Locator.waitFor() before single-element evaluations.","Verify selectors with .count() during authoring."],"tags":["selector","element-not-found","eval"],"backgroundTag":null,"analyzedSha":"c8fc3bf8d31542d59b4d4d9eaab1df93ff541dc6","analyzedAt":"2026-08-12T07:26:36.950Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}