Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

getByLabelText cannot find a label that is on the screen

ErrorUnable to find a label with the text of: Email

Short answer

The error means no label on the page matches the string you passed, or the label matched but is not tied to a form control. Read the DOM your test really rendered and compare the label text letter by letter. The usual causes: an exact-match mismatch, a caption that is not a label element, a broken for/id link, or a label that renders later.

  • Applies to @testing-library/react 16, @testing-library/dom 10, React 19, Jest 30
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Print the DOM at the moment the query runs. The first line of the error already splits the cases: 'Unable to find a label' means no label matched your text; 'Found a label ... however' means the text matched but the label is not wired to a control.

    import { screen } from '@testing-library/react';
    
    screen.debug();
  2. 2Match what you see, then jump to its fix

    1. 1Unable to find a label with the text of: Email, while the printed DOM shows a label such as 'Email address *' or 'Email:'Your string is not the label's whole textFix
    2. 2Unable to find a label with the text of: Email, and the printed DOM shows the words inside a div, span or Typography element beside the inputThe visible caption is not a labelFix
    3. 3Found a label with the text of: Email, however no form control was found associated to that labelThe label exists but its for attribute points nowhereFix
    4. 4however the element associated with this label (<section />) is non-labellableThe label points at an element that cannot be labelledFix
    5. 5The same query passes when you add a wait, or the printed DOM still shows a loading stateThe label is rendered after the query runsFix

What does the error look like?

  • Unable to find a label with the text of: Email
  • Found a label with the text of: Email, however no form control was found associated to that label. Make sure you're using the "for" attribute or "aria-labelledby" attribute correctly.
  • Found a label with the text of: Email, however the element associated with this label (<section />) is non-labellable

Cause 1 of 5

Your string is not the label's whole text

1Check

A string query is compared with the full label text, case-sensitive, after leading and trailing whitespace is trimmed and runs of spaces are collapsed. Text from child elements inside the label counts too, so a required-field star in a span becomes part of the text.

console.log(JSON.stringify(screen.getByText(/email/i).textContent));

2Fix

Pass the complete text, a case-insensitive regular expression, or turn off exact matching.

screen.getByLabelText(/^email/i);

// or accept any label that contains the text
screen.getByLabelText('Email', { exact: false });

3Verify

Run only the failing test file. The query now returns the input and the test reaches the next line.

npx jest src/components/LoginForm.test.jsx

Confirmed by testing-library.com

Did this fix it?

Cause 2 of 5

The visible caption is not a label

1Check

getByLabelText only follows real associations: a label with for/id, a label that wraps the control, aria-labelledby, or an aria-label attribute. Text that merely sits next to an input is not any of those.

screen.debug(screen.getByRole('textbox'));

2Fix

Render a real label tied to the input, or point aria-labelledby at the caption. In React the attribute is htmlFor.

<label htmlFor="login-email">Email</label>
<input id="login-email" type="email" />

3Verify

Run the test again, or query the control by its accessible name.

screen.getByLabelText('Email');
screen.getByRole('textbox', { name: 'Email' });

Confirmed by testing-library.com

Did this fix it?

Cause 3 of 5

The label exists but its for attribute points nowhere

1Check

The text matched, so the label is on the page. This message appears when the label has no control inside it and no for attribute, or its for value does not equal any id in the container.

const label = screen.getByText('Email');
console.log(label.getAttribute('for'));
console.log(document.getElementById(label.getAttribute('for')));

2Fix

Make the htmlFor value and the input id identical, or wrap the input inside the label.

<label htmlFor="login-email">Email</label>
<input id="login-email" type="email" />

3Verify

Run the test. The 'Found a label ... however' message should be gone.

npx jest src/components/LoginForm.test.jsx

Confirmed by github.com

Did this fix it?

Cause 4 of 5

The label points at an element that cannot be labelled

1Check

A for attribute that matches the id of a section, div or heading is not supported. Only form controls can be labelled this way.

console.log(document.getElementById(screen.getByText('Photos').getAttribute('for')).tagName);

2Fix

Move the id to the real control. If the thing you are naming is not a control, give it aria-label or aria-labelledby and query it with that.

<h2 id="photos-heading">Photos</h2>
<section aria-labelledby="photos-heading">...</section>

3Verify

Query the section by that label text.

screen.getByLabelText('Photos');

Confirmed by testing-library.com

Did this fix it?

Cause 5 of 5

The label is rendered after the query runs

1Check

getBy queries look at the DOM once and throw at once. A form that appears after a fetch or a state update is not there yet.

screen.debug(); // loading placeholder instead of the form

2Fix

Use the findBy variant, which waits and retries. Its default timeout is 1000 ms with a 50 ms interval.

const email = await screen.findByLabelText('Email');
expect(email).toBeInTheDocument();

3Verify

Run the test. If the form needs longer than a second, pass a larger timeout in the options.

await screen.findByLabelText('Email', {}, { timeout: 3000 });

Confirmed by testing-library.com

Did this fix it?

How do I stop it coming back?

  • Query by the accessible name first: getByRole with a name option fails the same way a screen reader user would fail, so it finds real markup problems.
  • Build forms from real label elements tied with htmlFor and id, never from a styled div next to an input.
  • Match label text with a case-insensitive regular expression when the copy contains punctuation or a required marker.
  • Add screen.debug() while writing the test, and remove it when the test passes.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.