Failed to find element matching one of the following queries

Error message

Failed to find element matching one of the following queries:
${queryDescriptions.map(desc => `(${desc})`).join(',
')}

What it means

The standard 'no match found' error of the CDK harness system, thrown by _assertResultFound when the first result of a locator/harnessLoader/getChildLoader query is undefined. locatorFor and harnessLoaderFor are strict by design — unlike locatorForOptional, they must find a match and throw otherwise. The message lists every query description that was tried.

Source

Thrown at src/cdk/testing/harness-environment.ts:500

        matchedHarnessTypes.add(result.constructor);
        dedupedMatches.push(result);
      }
    } else if (!testElementMatched) {
      testElementMatched = true;
      dedupedMatches.push(result);
    }
  }
  return dedupedMatches as T;
}

/** Verifies that there is at least one result in an array. */
async function _assertResultFound<T>(
  results: Promise<T[]>,
  queryDescriptions: string[],
): Promise<T> {
  const result = (await results)[0];
  if (result == undefined) {
    throw Error(
      `Failed to find element matching one of the following queries:\n` +
        queryDescriptions.map(desc => `(${desc})`).join(',\n'),
    );
  }
  return result;
}

/** Gets a list of description strings from a list of queries. */
function _getDescriptionForLocatorForQueries(queries: (string | HarnessQuery<any>)[]) {
  return queries.map(query =>
    typeof query === 'string'
      ? _getDescriptionForTestElementQuery(query)
      : _getDescriptionForComponentHarnessQuery(query),
  );
}

/** Gets a description string for a `ComponentHarness` query. */
function _getDescriptionForComponentHarnessQuery(query: HarnessQuery<any>) {

View on GitHub (pinned to 0411926e7d)

Solutions

Use locatorForOptional/getHarnessOrNull instead to handle 'may not exist' explicitly.
Call fixture.detectChanges()/await fixture.whenStable() before querying so the element is rendered.
Verify the selector/harness type matches what the template actually renders (check the query descriptions in the message).
Ensure the query runs under the right root loader (e.g. getChildLoader on the correct parent).

Example fix

// before
const btn = await loader.locatorFor('.save-button')();
// after
const btn = await loader.locatorForOptional('.save-button')();
if (!btn) throw new Error('Save button not rendered');

Defensive patterns

Strategy: fallback

Validate before calling

const count = (await loader.getAllHarnesses(ChildHarness)).length;
if (count === 0) { fixture.detectChanges(); await fixture.whenStable(); }

Type guard

const isFound = <T>(r: T | undefined): r is T => r !== undefined;

Try / catch

try { return await loader.locatorFor('.item')(); } catch (e) { if ((e as Error).message.includes('Failed to find element matching')) return locatorForOptional('.item')(); throw e; }

Prevention

Prefer locatorForOptional when absence is expected
Always stabilize the fixture (whenStable/detectChanges) before locating
Check selectors against the rendered template, not the spec assumptions

When it happens

Trigger: Calling locatorFor(query)(), harnessLoaderFor(query)(), or loader.getChildLoader(selector) when no element matches: wrong selector string, wrong harness type, element not yet rendered, or element outside the loader root.

Common situations: Typos in CSS selectors, querying components rendered conditionally (ngIf) that are absent in that test, missing fixture.detectChanges()/whenStable before querying, or harness from TestBed vs. manual environment mismatch.

Related errors

AI-assisted analysis of angular/components@0411926e7d (2026-08-31). Data as JSON: /api/errors/fd09639a7cabc0f0. Report an issue: GitHub.