HTML Guides

CSS: “background”: The first argument to the “linear-gradient” function should be “to top”, not “top”.

The linear-gradient() function went through several syntax revisions during CSS standardization. Early drafts and vendor-prefixed implementations (like -webkit-linear-gradient()) used bare direction keywords such as top, bottom left, etc., where the keyword indicated the starting point of the gradient. The final standard, defined in the CSS Images Module Level 3 and Level 4 specifications, changed this so that direction keywords use the to prefix and indicate the ending point of the gradient. For example, the old linear-gradient(top, #fff, #000) meant "start at the top and go to the bottom," while the correct modern equivalent is linear-gradient(to bottom, #fff, #000).

This matters because the old syntax without to is not valid CSS per the current specification. While some browsers may still interpret the legacy syntax for backward compatibility, relying on it is risky — behavior can vary across browsers, and it will trigger validation errors. Using standard-compliant CSS ensures consistent rendering and forward compatibility.

How to fix it

Replace the bare direction keyword with the correct to syntax. Note that the direction meaning is inverted: the old syntax specified where the gradient starts, while the new syntax specifies where it goes to.

Here's a quick mapping from old to new syntax:

Old (invalid)	New (valid)	Angle equivalent
`top`	`to bottom`	`180deg`
`bottom`	`to top`	`0deg`
`left`	`to right`	`90deg`
`right`	`to left`	`270deg`
`top left`	`to bottom right`	N/A (use `to` syntax)

Important: Notice that top in the old syntax means "start at top, go to bottom." So the modern equivalent is to bottom, not to top. If the validator message says the argument should be to top, it means you wrote top — but be sure you understand which direction your gradient should actually go before blindly replacing it. If you truly want the gradient to go toward the top, use to top. If you want it to go from the top downward, use to bottom.

If you don't specify a direction at all, linear-gradient() defaults to to bottom (top-to-bottom), which is often what you want.

Examples

Invalid: bare direction keyword

Content

</div>

The bare keyword top is not valid in the standard linear-gradient() syntax and will trigger the validator error.

Fixed: using the `to` keyword

Content

</div>

Since the old top meant "start at the top," the equivalent standard syntax is to bottom.

Fixed: using an angle

Content

</div>

An angle of 180deg produces the same top-to-bottom gradient.

Full document example

<!DOCTYPE html>

<head>

<title>Gradient Example</title>

<style>

.box {

width: 200px;

height: 100px;

/* Valid: direction keyword with "to" */

background: linear-gradient(to top, #ffffff, #000000);

}

.box-angle {

width: 200px;

height: 100px;

/* Valid: angle equivalent of "to top" */

background: linear-gradient(0deg, #ffffff, #000000);

}

.box-default {

width: 200px;

height: 100px;

/* Valid: no direction specified, defaults to "to bottom" */

background: linear-gradient(#ffffff, #000000);

}

</style>

</head>

<body>

</body>

</html>

All three approaches are valid. Choose whichever is clearest for your use case — the to keyword syntax is generally the most readable, while angles offer more precision for diagonal or non-cardinal directions.

Bad value for attribute “src” on element “img”: Illegal character in scheme data: “<” is not allowed.

Document uses the Unicode Private Use Area(s), which should not be used in publicly exchanged documents.

Private Use Area (PUA) characters are reserved ranges in Unicode whose interpretation is not specified by any encoding standard. Their meaning is determined entirely by private agreement between cooperating parties—such as a font vendor and its users. This means that a PUA character that renders as a custom icon in one font may appear as a blank square, a question mark, or a completely different glyph when that specific font is unavailable.

This warning commonly appears when using icon fonts like older versions of Font Awesome, Material Icons, or custom symbol fonts. These fonts map their icons to PUA code points. While this approach works visually when the font loads correctly, it creates several problems:

Accessibility: Screen readers cannot interpret PUA characters meaningfully. A visually impaired user may hear nothing, hear "private use area character," or hear an unrelated description depending on their assistive technology.
Portability: If the associated font fails to load (due to network issues, content security policies, or user preferences), the characters become meaningless boxes or blank spaces.
Interoperability: Copy-pasting text containing PUA characters into another application, email client, or document will likely produce garbled or missing content since the receiving system won't know how to interpret those code points.
Standards compliance: The W3C and Unicode Consortium both recommend against using PUA characters in publicly exchanged documents for exactly these reasons.

Sometimes PUA characters sneak into your HTML unintentionally—through copy-pasting from word processors, PDFs, or design tools that use custom encodings. Other times, they are inserted deliberately via CSS content properties or HTML entities by icon font libraries.

To fix this, identify where the PUA characters appear and replace them with standard alternatives. Use inline SVG for icons, standard Unicode symbols where appropriate (e.g., ✓ U+2713 instead of a PUA checkmark), or CSS background images. If you must use an icon font, hide the PUA character from assistive technology using aria-hidden="true" and provide an accessible label separately.

Examples

Problematic: PUA character used directly in HTML

<p>Status: </p>

Without the specific icon font loaded, PUA characters like U+E001 render as missing glyphs or blank spaces.

Fixed: Using inline SVG with accessible label

<p>

Status:

</svg>

<span>Complete</span>

</p>

Problematic: Icon font via CSS content property

<style>

.icon-check::before {

font-family: "MyIcons";

content: "\e001"; /* PUA character */

}

</style>

Fixed: Icon font with accessibility safeguards

If you must continue using an icon font, hide the PUA character from assistive technology and provide an accessible alternative:

<style>

.icon-check::before {

font-family: "MyIcons";

content: "\e001";

}

</style>

<span class="sr-only">Checkmark</span>

Note that this approach still triggers the validator warning if the PUA character is detectable in the markup. The most robust fix is to avoid PUA characters entirely.

Fixed: Using a standard Unicode character

<p>Status: ✓ Complete</p>

The character ✓ (U+2713, CHECK MARK) is a standard Unicode character that is universally understood and renders consistently across platforms.

Problematic: PUA character from copy-paste

<p>Click here to download</p>

Invisible or unexpected PUA characters sometimes hide in text pasted from external sources. Inspect your source code carefully—many code editors can highlight non-ASCII characters or reveal their code points.

Fixed: Cleaned-up text

<p>Click here to download</p>

If you've audited your document and determined that the PUA characters are intentional and rendering correctly in your target environments, you may choose to accept this warning. However, for publicly accessible web pages, replacing PUA characters with standard alternatives is always the safer and more accessible choice.

Bad value X for attribute “href” on element “a”: Illegal character in fragment: “>” is not allowed.

A URL fragment identifier is the part of a URL that follows the # symbol, typically used to link to a specific section within a page. The URL specification (RFC 3986 and the WHATWG URL Standard) defines a strict set of characters that are permitted in fragments. The > character (greater-than sign) is among those that are not allowed to appear literally. When the W3C HTML Validator encounters > inside an href value — whether in the fragment or elsewhere in the URL — it raises this error.

In most cases, the > character appears in a URL by accident — for example, from a copy-paste error, a typo where the closing > of the tag accidentally ends up inside the attribute value, or a malformed template expression. Less commonly, a developer may genuinely need the > character as part of the URL content.

Why This Matters

Broken links: Browsers may interpret the > as the end of the HTML tag or handle the URL unpredictably, leading to broken navigation.
Standards compliance: Invalid URLs violate both the HTML specification and URL syntax standards, causing validation failures.
Accessibility: Screen readers and other assistive technologies rely on well-formed markup. A malformed href can confuse these tools and prevent users from reaching the intended destination.
Interoperability: While some browsers may silently correct or ignore the invalid character, others may not. Valid URLs guarantee consistent behavior everywhere.

How to Fix It

If the > is a typo or copy-paste error, simply remove it from the href value. This is the most common scenario.
If the > is intentionally part of the fragment or URL, replace it with its percent-encoded equivalent: %3E.
Review your templates or CMS output — this error often originates from template engines or content management systems that inject malformed values into href attributes.

Examples

Accidental `>` in the URL path

A common mistake is accidentally including the tag's closing > inside the attribute value:

Remove the stray >:

Illegal `>` in a fragment identifier

The > can also appear inside the fragment portion of the URL:

<a href="/docs#section->overview">Go to overview</a>

If the > is unintentional, remove it:

<a href="/docs#section-overview">Go to overview</a>

If the > is genuinely needed in the fragment, percent-encode it:

<a href="/docs#section-%3Eoverview">Go to overview</a>

Query string or path containing `>`

The same rule applies outside of fragments. If > appears anywhere in the URL, encode it:

<a href="/search?filter=price>100">Expensive items</a>

<a href="/search?filter=price%3E100">Expensive items</a>

Template output errors

If you are using a server-side template or JavaScript framework, ensure that dynamic values inserted into href are properly URL-encoded. For example, in a template that generates links:

<a href="/results#filter=>50">View results</a>

<a href="/results#filter=%3E50">View results</a>

Most server-side languages provide built-in URL encoding functions (e.g., encodeURIComponent() in JavaScript, urlencode() in PHP, urllib.parse.quote() in Python) that will handle this automatically. Always use these functions when inserting dynamic content into URLs.

Bad value X for attribute “href” on element “a”: Illegal character in fragment. “|” is not allowed.

Bad value X for attribute “ping” on element “a”: Must contain only “http” or “https” URLs.

The ping attribute specifies a space-separated list of URLs that the browser should notify (via a small POST request) when a user follows a hyperlink. This is commonly used for click tracking and analytics. According to the HTML specification, every URL in the list must be a valid, non-empty URL that uses either the http or https scheme — no other schemes or relative paths are permitted.

This restriction exists for practical and security reasons. The ping mechanism is specifically designed for web-based tracking endpoints, so only web protocols make sense. Relative URLs are disallowed because the ping is sent as a separate request independent of normal navigation, and the specification requires absolute URLs to unambiguously identify the target server. Using invalid values won't produce the intended tracking behavior and will cause the browser to silently ignore the ping attribute entirely.

From an accessibility and standards compliance standpoint, ensuring valid ping values means your analytics will work reliably in browsers that support the attribute. Note that browser support varies — some browsers (notably Firefox) disable ping by default or hide it behind a preference — so you should not rely on it as your sole tracking mechanism.

How to fix it

Replace relative URLs with absolute URLs. If you have a value like /track or track.php, prepend the full origin (e.g., https://example.com/track).
Remove non-HTTP schemes. Values like mailto:someone@example.com or ftp://example.com/log are not valid for ping.
Ensure each URL in the list is properly formatted. Multiple URLs must be separated by spaces (not commas or semicolons), and each one must be a complete http or https URL.

Examples

Incorrect: relative URL

<a href="https://example.com" ping="/track">Visit Example</a>

The value /track is a relative URL, which is not allowed in the ping attribute.

Incorrect: unsupported scheme

<a href="https://example.com" ping="ftp://example.com/log">Visit Example</a>

The ftp: scheme is not permitted — only http and https are valid.

Incorrect: comma-separated URLs

<a href="https://example.com" ping="https://example.com/track, https://analytics.example.com/log">Visit Example</a>

Multiple URLs must be space-separated, not comma-separated. The commas make each URL invalid.

Correct: single absolute URL

<a href="https://example.com" ping="https://example.com/track">Visit Example</a>

Correct: multiple space-separated absolute URLs

<a href="https://example.com" ping="https://example.com/track https://analytics.example.com/log">Visit Example</a>

Each URL is a fully qualified https URL, and they are separated by a single space. Both will receive a POST request when the link is clicked (in browsers that support the ping attribute).

Bad value X for attribute “href” on element “a”: Illegal character in query. “|” is not allowed.

Bad value “mailto:X” for attribute “href” on element “a”: Illegal character after “ilto:”. “<” is not allowed.

Bad value “” for attribute “imagesrcset” on element “link”: Must contain one or more image candidate strings.

Bad value for attribute “action” on element “form”: Percentage ("%") is not followed by two hexadecimal digits.

In URLs, certain characters must be percent-encoded — a process where a character is replaced by % followed by exactly two hexadecimal digits representing its byte value. For example, a space becomes %20, a hash becomes %23, and an ampersand becomes %26. The % character itself is the escape prefix, so when a URL parser encounters %, it expects the next two characters to be valid hexadecimal digits (0–9, A–F, a–f). If they aren't, the URL is malformed.

This validation error typically arises in a few scenarios:

A literal % is used in the URL without encoding. For instance, a filename or path segment contains a % sign that wasn't converted to %25.
An incomplete or corrupted percent-encoding sequence. Someone may have partially encoded a URL, leaving behind sequences like %G5 or %2 that don't form valid two-digit hex codes.
Copy-paste errors. A URL was pasted from a source that stripped characters or introduced stray % symbols.

This matters because browsers may interpret malformed URLs inconsistently. One browser might try to "fix" the URL by encoding the stray %, while another might pass it through as-is, leading to broken form submissions or unexpected server-side behavior. Ensuring valid URLs in the action attribute guarantees predictable behavior across all browsers and complies with both the WHATWG URL Standard and the HTML specification.

How to Fix

Locate every % in the URL. Check whether each % is followed by exactly two hexadecimal digits (e.g., %20, %3A, %7E).
Encode literal % characters. If a % is meant to appear as a literal character in the URL (not as part of a percent-encoding sequence), replace it with %25.
Fix incomplete sequences. If a sequence like %2 or %GZ exists, determine the intended character and encode it correctly, or remove the stray %.
Use proper encoding tools. In JavaScript, use encodeURIComponent() or encodeURI() to safely encode URLs. Most server-side languages have equivalent functions (e.g., urlencode() in PHP, urllib.parse.quote() in Python).

Examples

Literal `%` not encoded

This triggers the error because %d is not a valid percent-encoding sequence (d is only one character, and what follows may not be hex):

<button type="submit">Search</button>

</form>

Encode the % as %25:

<button type="submit">Search</button>

</form>

Incomplete percent-encoding sequence

Here, %2 is missing its second hex digit:

<button type="submit">Submit</button>

</form>

If the intent was to encode a / character (%2F), complete the sequence:

<button type="submit">Submit</button>

</form>

Invalid hex characters after `%`

The characters G and Z are not hexadecimal digits:

</form>

If %GZ was never intended as encoding, escape the % itself:

</form>

Using JavaScript to encode safely

When building URLs dynamically, use built-in encoding functions to avoid this issue entirely:

const query = "20% off";

const safeURL = "/search?q=" + encodeURIComponent(query);

// Result: "/search?q=20%25%20off"

This ensures every special character — including % — is properly percent-encoded before it's placed in the action attribute.

The document is not mappable to XML 1.0 due to two consecutive hyphens in a comment.

The HTML specification restricts what can appear inside a comment. Specifically, a comment must not contain the string -- (two consecutive hyphens) except as part of the opening and closing delimiters. This rule originates from SGML and XML 1.0, where -- is treated as a comment delimiter, and having extra occurrences inside the comment body creates ambiguity about where the comment starts and ends.

While most modern browsers are lenient and will handle comments with double hyphens without issues, the markup is technically invalid. This matters for several reasons:

XML compatibility: If your HTML is served as XHTML or processed by XML parsers, double hyphens inside comments will cause parsing errors and potentially break the entire document.
Standards compliance: The HTML living standard explicitly states that comments must not contain --, so validators flag this as an error.
Predictable parsing: Different parsers may interpret malformed comments differently, leading to inconsistent behavior across tools, crawlers, and assistive technologies.

To fix the issue, look inside your comment text and replace any occurrence of -- with something else, such as a single hyphen, an equals sign, or a different separator.

Examples

Incorrect: double hyphens inside the comment body

The string of hyphens inside the comment contains multiple consecutive -- pairs, making the comment invalid.

Here, -- appears literally in the comment text, which violates the rule.

Multiple -- sequences appear as casual text separators, each one triggering the validation error.

Correct: avoiding double hyphens

Replace double hyphens with a different character or pattern:

Correct: standard comment syntax

Simple comments that don't contain -- in their body are perfectly valid:

<!--

Multi-line comments are fine too,

as long as they don't contain double hyphens.

-->

Common pitfall: decorative comment borders

Developers sometimes use hyphens to create visual separators in their source code:

Replace these with a different character:

Or simply remove the decorative lines:

Bad value “” for attribute “tabindex” on element “X”: The empty string is not a valid integer.

tabindex

Bad value X for attribute “src” on element “iframe”: Illegal character in query: “[” is not allowed.

When the W3C HTML Validator reports "Bad value X for attribute src on element iframe: Illegal character in query: [ is not allowed", it means your URL contains unencoded square brackets in the query portion (everything after the ?). While most modern browsers will silently handle these characters and load the resource anyway, the URL does not conform to the URI syntax defined in RFC 3986, which the HTML specification requires.

According to RFC 3986, square brackets are reserved characters that have a specific purpose: they are only permitted in the host component of a URI to denote IPv6 addresses (e.g., http://[::1]/). Anywhere else in the URI — including the query string — they must be percent-encoded. The HTML living standard (WHATWG) requires that URLs in attributes like src, href, and action be valid URLs, which means they must follow these encoding rules.

Why this matters

Standards compliance: Invalid URLs cause W3C validation failures, which can indicate deeper issues in your markup.
Interoperability: While mainstream browsers are forgiving, some HTTP clients, proxies, CDNs, or web application firewalls may reject or mangle URLs with unencoded square brackets.
Consistent behavior: Percent-encoding reserved characters guarantees that the URL is interpreted the same way everywhere — in browsers, server logs, link checkers, and automated tools.
Copy-paste reliability: When users or tools copy a URL from your HTML source, an already-encoded URL is less likely to break during transmission through email clients, messaging apps, or other systems.

How to fix it

Replace every occurrence of [ with %5B and ] with %5D within the query string of the URL. If you're generating URLs server-side or in JavaScript, use the language's built-in URL encoding functions rather than doing manual find-and-replace:

JavaScript: encodeURIComponent() or the URL / URLSearchParams APIs
PHP: urlencode() or http_build_query()
Python: urllib.parse.urlencode() or urllib.parse.quote()

These functions will automatically encode square brackets and any other reserved characters.

Examples

❌ Invalid — unencoded square brackets in query string

The validator flags [ and ] as illegal characters in the query component.

✅ Valid — square brackets percent-encoded

Replacing [ with %5B and ] with %5D resolves the error. The server receives the exact same parameter values — most server-side frameworks (PHP, Rails, etc.) automatically decode percent-encoded characters before processing them.

❌ Invalid — square brackets in a timestamp parameter

✅ Valid — timestamp parameter properly encoded

Generating encoded URLs in JavaScript

If you're setting the src dynamically, let the browser handle encoding for you:

const url = new URL("https://example.com/embed");

url.searchParams.set("filter[status]", "active");

url.searchParams.set("filter[type]", "video");

document.getElementById("report-frame").src = url.toString();

</script>

The URLSearchParams API automatically percent-encodes the brackets, producing a valid URL in the src attribute.

A note on other elements

This same rule applies to any HTML attribute that accepts a URL — including href on <a> elements, action on <form> elements, and src on <script> or <img> elements. Whenever you place a URL in HTML, ensure all reserved characters in the query string are properly percent-encoded.

Bad value for attribute “src” on element “img”: Illegal character in fragment: space is not allowed.

Bad value X for attribute “href” on element “a”: Illegal character in fragment: “” is not allowed.

Bad value for attribute “href” on element “a”: Illegal character in query. Space is not allowed.

Bad value X for attribute “href” on element “a”: Illegal character after “ilto:”. “[” is not allowed.

The “aria-labelledby” attribute must not be specified on any “span” element unless the element has a “role” value other than “caption”, “code”, “deletion”, “emphasis”, “generic”, “insertion”, “paragraph”, “presentation”, “strong”, “subscript”, or “superscript”.

The “aria-label” attribute must not be specified on any “a” element unless the element has a “role” value other than “caption”, “code”, “deletion”, “emphasis”, “generic”, “insertion”, “paragraph”, “presentation”, “strong”, “subscript”, or “superscript”.

The “aria-label” attribute must not be specified on any “span” element unless the element has a “role” value other than “caption”, “code”, “deletion”, “emphasis”, “generic”, “insertion”, “paragraph”, “presentation”, “strong”, “subscript”, or “superscript”.

The “aria-label” attribute must not be specified on any “div” element unless the element has a “role” value other than “caption”, “code”, “deletion”, “emphasis”, “generic”, “insertion”, “paragraph”, “presentation”, “strong”, “subscript”, or “superscript”.

The “aria-label” attribute must not be specified on any “time” element unless the element has a “role” value other than “caption”, “code”, “deletion”, “emphasis”, “generic”, “insertion”, “paragraph”, “presentation”, “strong”, “subscript”, or “superscript”.

The “aria-labelledby” attribute must not be specified on any “div” element unless the element has a “role” value other than “caption”, “code”, “deletion”, “emphasis”, “generic”, “insertion”, “paragraph”, “presentation”, “strong”, “subscript”, or “superscript”.

The “aria-label” attribute must not be specified on any “i” element unless the element has a “role” value other than “caption”, “code”, “deletion”, “emphasis”, “generic”, “insertion”, “paragraph”, “presentation”, “strong”, “subscript”, or “superscript”.

An inline “script” element (i.e., a “script” element without a “src” attribute and with a “type” attribute that is either unspecified, empty, or a JavaScript MIME type) must not have a “defer” attribute.

How to fix it

Examples

Invalid: bare direction keyword

Fixed: using the to keyword

Fixed: using an angle

Full document example

How to fix it

Examples

Incorrect — template syntax in src

Incorrect — HTML accidentally inside src

Correct — a valid relative URL

Correct — a valid absolute URL

Correct — special characters percent-encoded

Examples

Problematic: PUA character used directly in HTML

Fixed: Using inline SVG with accessible label

Problematic: Icon font via CSS content property

Fixed: Icon font with accessibility safeguards

Fixed: Using a standard Unicode character

Problematic: PUA character from copy-paste

Fixed: Cleaned-up text

Why This Matters

How to Fix It

Examples

Accidental > in the URL path

Illegal > in a fragment identifier

Query string or path containing >

Template output errors

Invalid example

Valid example

How to fix it

Examples

Incorrect: relative URL

Incorrect: unsupported scheme

Incorrect: comma-separated URLs

Correct: single absolute URL

Correct: multiple space-separated absolute URLs

HTML examples

Invalid example

Valid example

Invalid example

Valid example

How to fix it

Examples

❌ Empty imagesrcset triggers the error

✅ Valid imagesrcset with width descriptors

✅ Valid imagesrcset with pixel density descriptors

✅ Removing the attribute when no responsive sources exist

✅ Conditional rendering in a template

How to Fix

Examples

Literal % not encoded

Incomplete percent-encoding sequence

Invalid hex characters after %

Using JavaScript to encode safely

Examples

Incorrect: double hyphens inside the comment body

Correct: avoiding double hyphens

Correct: standard comment syntax

Common pitfall: decorative comment borders

Why this matters

How tabindex works

How to fix it

Examples

❌ Empty tabindex value (triggers the error)

✅ Fixed: valid integer provided

✅ Fixed: attribute removed when not needed

✅ Fixed: conditional rendering in a template

A note on positive tabindex values

Why this matters

How to fix it

Examples

❌ Invalid — unencoded square brackets in query string

✅ Valid — square brackets percent-encoded

❌ Invalid — square brackets in a timestamp parameter

✅ Valid — timestamp parameter properly encoded

Generating encoded URLs in JavaScript

A note on other elements

HTML examples

Fixed: using the `to` keyword

Incorrect — template syntax in `src`

Incorrect — HTML accidentally inside `src`

Accidental `>` in the URL path

Illegal `>` in a fragment identifier

Query string or path containing `>`

❌ Empty `imagesrcset` triggers the error

✅ Valid `imagesrcset` with width descriptors

✅ Valid `imagesrcset` with pixel density descriptors

Literal `%` not encoded

Invalid hex characters after `%`

How `tabindex` works

❌ Empty `tabindex` value (triggers the error)

A note on positive `tabindex` values

❌ Invalid: `aria-labelledby` on a plain `span`

✅ Fix: Add an appropriate `role`

❌ Invalid: `aria-label` on an `<a>` without `href`

✅ Fix option 1: Add an `href`

✅ Fix option 2: Use a `<button>` instead

❌ Invalid: `aria-label` on a plain `span`

✅ Fixed: hide the decorative `span` and provide text another way

❌ Invalid: `aria-label` on a plain `div`

✅ Fix: Add an appropriate `role`

❌ Invalid: `aria-label` on `<time>`

✅ Fixed: Remove `aria-label` and use clear visible text

❌ Invalid: `aria-labelledby` on a plain `div`

✅ Fixed: Add a meaningful `role` to the `div`

❌ Invalid: `aria-label` on a plain `<i>` element

✅ Fix 2: Meaningful icon — assign `role="img"`

Validate at scale.
Ship accessible websites, faster.