HTML Guide
The validator error occurs when an element such as an a, button, or custom widget includes aria-controls="" (empty) or whitespace-only. The aria-controls attribute takes one or more space-separated id values (IDREFS). Each referenced id must exist exactly once in the same document. Leaving it empty violates the ARIA and HTML requirements and provides no usable relationship for assistive technologies.
Why this matters:
-
Accessibility: Screen readers rely on
aria-controlsto announce relationships between controls and controlled regions (e.g., a toggle and its panel). An empty value misleads AT or adds noise. -
Standards compliance: HTML and ARIA require at least one non-whitespace
id. Empty values cause validation failures. - Robustness: Incorrect references can confuse scripts and future maintainers, and break behavior when IDs change.
How to fix it:
-
Only add
aria-controlswhen the element truly controls another region (show/hide, sort, update). -
Ensure the controlled element has a unique
id. -
Set
aria-controlsto thatid(or multiple space-separated IDs). - Keep the reference in sync if IDs change.
-
If nothing is controlled, remove
aria-controlsentirely.
Examples
Invalid: empty aria-controls (triggers the error)
<a href="#" aria-controls="">Toggle details</a>Valid: control a single region
<div id="details-panel" hidden>
Some details...
</div>
<a href="#details-panel" aria-controls="details-panel">Toggle details</a>Valid: control multiple regions (space-separated IDs)
<section id="filters" hidden>...</section>
<section id="results" hidden>...</section>
<button type="button" aria-controls="filters results">Show filters and results</button>Valid: remove when not needed
<a href="#">Toggle details</a>Minimal complete document with proper usage
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>aria-controls Example</title>
</head>
<body>
<button type="button" aria-controls="info" aria-expanded="false">Toggle info</button>
<div id="info" hidden>
Extra information.
</div>
<script>
const btn = document.querySelector('button');
const panel = document.getElementById(btn.getAttribute('aria-controls'));
btn.addEventListener('click', () => {
const expanded = btn.getAttribute('aria-expanded') === 'true';
btn.setAttribute('aria-expanded', String(!expanded));
panel.hidden = expanded;
});
</script>
</body>
</html>Tips:
-
Use
aria-controlsfor functional relationships (control affects content), not just visual proximity. -
Combine with
aria-expandedwhen toggling visibility to convey state. -
Verify that every
idinaria-controlsexists and is unique; avoid dynamic mismatches created by templating or component reuse.
Learn more:
Last reviewed: February 13, 2026
Related W3C validator issues
Spaces are not permitted in the href value for phone links; the phone number must be a continuous string without spaces or slashes.
The href attribute of an anchor (<a>) element defines the link’s destination. For phone numbers, the proper URI scheme is tel:, not callto:. According to the HTML standard and the WHATWG Living Standard, the phone number should contain only digits and may use plus (+) or hyphen (-) characters for formatting, but it should not include spaces or slashes.
Incorrect HTML:
<a href="callto:07142/ 12 34 5">Call us</a>Correct HTML:
<a href="tel:0714212345">Call us</a>With country code and optional formatting:
<a href="tel:+49714212345">Call us</a>For best compatibility and validation, always use the tel: scheme and ensure the phone number string contains only allowed characters.
The dialog element does not require or permit a role="dialog" attribute according to HTML standards.
The <dialog> element has an implicit ARIA role of dialog, so adding role="dialog" is redundant and not valid per the specification. Instead, simply use the <dialog> element without an explicit role attribute.
Details:
According to the WHATWG HTML standard and ARIA specification, native <dialog> elements automatically have the correct role. Adding role="dialog" can cause HTML validation errors, as the validator interprets this as a misuse or redundancy.
Correct usage:
<dialog>
<p>This is a dialog box.</p>
<button>Close</button>
</dialog>Incorrect usage (causes validation error):
<dialog role="dialog">
<p>This is a dialog box.</p>
<button>Close</button>
</dialog>Removing the role="dialog" attribute resolves the W3C validation issue while maintaining accessibility.
Spaces in the URL fragment are invalid; encode them or remove them (e.g., use %20 or hyphens/underscores).
The href attribute must contain a valid URL. When using a fragment identifier (the part after #), it must follow URL syntax rules: no unescaped spaces. Fragments usually reference an element’s id. An element’s id must be unique and is case-sensitive; while spaces aren’t allowed in id values, many authors accidentally mirror text with spaces in the fragment. Use hyphens or underscores in ids and match the fragment, or percent-encode reserved characters. Prefer readable, dash-separated ids for accessibility and shareable links.
For example, instead of href=”#My Section”, use href=”#my-section” and set id=”my-section” on the target. If you must preserve spaces in a generated URL, encode them as %20, but it’s better to avoid spaces entirely in ids.
HTML Examples
Invalid: reproduces the validator error
<!doctype html>
<html lang="en">
<head>
<title>Fragment with space</title>
</head>
<body>
<a href="#My Section">Go to section</a>
<h2 id="My Section">My Section</h2>
</body>
</html>Fixed: use a valid fragment and id
<!doctype html>
<html lang="en">
<head>
<title>Valid fragment</title>
</head>
<body>
<a href="#my-section">Go to section</a>
<h2 id="my-section">My Section</h2>
</body>
</html>Alternatively, encoding the space also passes validation, though less ideal as the id would be invalid because it contains spaces:
<a href="#My%20Section">Go to section</a>
<h2 id="My Section">My Section</h2>The href attribute of an <a> element contains an invalid character, that should be properly encoded as a URI percent-encoded character.
The pipe character | is not permitted in the query component of a URL in the href attribute of an a element.
According to the WHATWG and W3C HTML specifications, URLs in attributes such as href must be valid and properly encoded. The pipe character | is not a valid character in the query string of a URL unless it is percent-encoded as %7C. Failing to encode it will cause validation errors. This is especially important for interoperability and security across browsers and user agents.
Incorrect example (invalid href with pipe):
<a href="https://example.com/search?q=test|demo">Invalid link</a>Correct example (pipe character encoded):
<a href="https://example.com/search?q=test%7Cdemo">Valid link</a>Always encode special characters such as | in URLs used within HTML attributes to ensure your documents validate and behave consistently.
Space characters are not permitted in the value of the href attribute; they must be properly percent-encoded.
The href attribute specifies a URL, and URLs must follow specific syntax rules defined by RFC 3986. Spaces and some other characters are considered illegal in URLs. To include a space in the URL, use the percent escape sequence %20 in place of the space character.
Incorrect example with an illegal space in the query string:
<a href="search.html?q=my search">Search for 'my search'</a>Correct example using percent-encoding for the space:
<a href="search.html?q=my%20search">Search for 'my search'</a>Replace all spaces in URLs within href attributes with %20 to ensure W3C validation and proper browser behavior.
Square brackets ([, ]) are not allowed unescaped in the query part of an href URL value.
The href attribute in the <a> element must contain a valid URL. According to the URL standard, certain characters, including square brackets, are not permitted directly in the query component unless percent-encoded. Using unescaped square brackets in the URL can cause validation errors and unexpected behavior in browsers.
To include a square bracket in the query string, use percent encoding:
- [ encodes to %5B
- ] encodes to %5D
Incorrect usage:
<a href="search.html?q=[value]">Search</a>Correct usage:
<a href="search.html?q=%5Bvalue%5D">Search</a>This ensures the URL is valid and compliant with HTML standards.
The href attribute of the a element contains an invalid backslash character, which is not permitted in URLs.
According to the WHATWG HTML living standard, the href attribute must contain a valid URL. URLs use forward slashes (/) for path separators, and backslashes are not allowed as they can cause browsers and validators to misinterpret the address. Backslashes often arise when file paths are copied from Windows environments.
Correct Usage:
- Always use forward slashes / in your URLs.
- Remove any backslashes from href values.
Example of incorrect usage:
<a href="images\picture.jpg">View Picture</a>Corrected example:
<a href="images/picture.jpg">View Picture</a>Empty type attributes are invalid on the <a> element; you must either remove the type attribute or provide a valid MIME type value.
The type attribute on an <a> (anchor) element specifies the MIME type of the linked resource. According to the WHATWG HTML specification and W3C validator, the value of the type attribute cannot be an empty string. It should be a valid MIME type, such as application/pdf or text/html. If you do not know the MIME type or it’s not relevant, you should omit the attribute.
Incorrect HTML example (causes validation error):
<a href="document.pdf" type="">Download PDF</a>Correct HTML example (remove the invalid attribute):
<a href="document.pdf">Download PDF</a>Correct HTML example (provide a valid MIME type):
<a href="document.pdf" type="application/pdf">Download PDF</a>If the type is unknown or unnecessary, leaving it out is preferred to using an empty value.
The icon value for attribute role is not a valid ARIA role.
ARIA Roles: Overview
ARIA roles are used to enhance accessibility by clearly defining the role and purpose of an element for assistive technologies. However, there are defined roles that you need to adhere to:
- Standard roles include button, checkbox, alert, dialog, img, etc.
- There is no ARIA role named icon.
Solution
To fix the issue, you need to use a valid ARIA role that accurately describes the purpose of the span element. If your intention is to convey that the span contains an icon, you might want to reconsider whether you need a role at all. Often, purely decorative elements should not have a role, or you might use an img role if it conveys a meaningful image.
Here’s how you can address this:
-
No ARIA role (if purely decorative): If the icon is purely decorative and does not add meaningful content to your page, you should remove the role attribute entirely.
<span class="icon"></span> -
Using img role (if it represents an image): If the span represents an image or an icon that conveys meaningful information, you can use role="img" and provide a proper aria-label.
<span class="icon" role="img" aria-label="Icon Description"></span> -
Using an appropriate role (if interactive): If the icon is part of an interactive element, you might need a different role. For instance, if the icon is inside a button:
<button> <span class="icon" aria-hidden="true"></span> Button text </button>Here, aria-hidden="true" is used to hide the decorative icon from screen readers as the text provides the necessary context.