SiteLint documentation and guidelines

Broken or malformed data URL images

Description

This rule identifies <img> elements whose src attribute uses a data URL that is either malformed or fails to decode. A data URL embeds image content directly in the HTML as a base64-encoded or percent-encoded string. The rule performs two checks: it validates the data URL syntax against the data:[<mediatype>][;base64],<data> format and verifies that the browser could successfully decode the image (by checking naturalWidth === 0 && complete on the HTMLImageElement). When a data URL is corrupt, truncated, or improperly encoded, the browser wastes CPU cycles attempting to parse it, which delays page rendering and harms the user experience.

Why it matters

Broken data URL images directly degrade Core Web Vitals. If a data URL is used on the Largest Contentful Paint (LCP) candidate and fails to decode, the browser may stall the LCP element until the decoding attempt times out, inflating the LCP score. The main thread spends valuable cycles parsing invalid base64 strings, which contributes to longer Interaction to Next Paint (INP) response times during user interactions. Invalid data URLs also increase the page’s memory footprint since the raw base64 string is held in the DOM regardless of decode success. From a user perspective, a broken inline image produces no visible content and no fallback, making the page appear incomplete or broken. Resolving these issues ensures images render at full speed and eliminates wasted CPU work on the critical rendering path.

Coding problems and solutions

Common coding problems

  • Malformed data URL syntax – Missing the required data: prefix or the comma separator between the media-type declaration and the encoded data. The browser cannot identify the string as a valid data URL.
  • Invalid base64 characters – Using characters outside the standard base64 alphabet (A–Z, a–z, 0–9, +, /, =). Non-printable or special characters cause the decode to fail.
  • Empty or truncated base64 data – The data portion after the comma is empty (e.g., data:image/png;base64,) or the base64 string is cut off mid-stream, producing an incomplete payload.
  • Missing or incorrect MIME type – Omitting the media type (e.g., data:;base64,…) or declaring a MIME type that does not match the actual encoded content forces the browser to guess the format.
  • Oversized unoptimized payloads – Embedding large, unoptimized images as data URLs bloats the HTML and increases the likelihood of truncation during build-time processing or copy-paste errors.

How to fix it

Validate data URLs before rendering

Always validate the data URL format in JavaScript before assigning it to an <img> element’s src attribute. A simple regex check can catch malformed syntax early and redirect to a fallback.

Correct example
const isValidDataUrl = (url) => {
  const match = url.match(/^data:([^,]+),(.+)$/);

  if (match === null) {
    return false;
  }

  const data = match[2];

  if (match[1].includes(';base64')) {
    return /^[A-Za-z0-9+/]*={0,2}$/.test(data) && data.length > 0;
  }

  try {
    return globalThis.decodeURIComponent(data).length > 0;
  } catch {
    return false;
  }
};

if (isValidDataUrl(rawUrl)) {
  img.src = rawUrl;
} else {
  img.src = 'fallback-placeholder.png';
}
Incorrect example
// No validation – assumes every data URL is valid
img.src = rawUrl;
// If rawUrl is "data:image/png;base64,Invalid!!",
// the browser wastes CPU decoding invalid characters

Use proper base64 encoding pipelines

Generate base64 output from trusted tools (image processing libraries, CLI utilities) rather than manual or ad-hoc encoding. A wrong character or missing padding (=) can break the entire image.

Correct example
<!-- Encoded with a proper tool: base64 image.png -->
<img src="data:image/webp;base64,UklGRkZGAABXRUJQVlA4WAoAAAAQAAAASwAASwAAQUxQSIcBAAABkI" alt="Optimized illustration">
Incorrect example
<!-- Missing trailing padding "=" – decode will fail on many parsers -->
<img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAA" alt="Badly encoded icon">

Provide fallback images for decode failures

Attach an onerror handler to swap the src to a static placeholder when the data URL image fails to render. This catches cases where the data URL passes syntax validation but still fails to decode in a specific browser or environment.

Correct example
<img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="
     alt="Decorative shape"
     onerror="this.src='fallback-broken.svg'; this.onerror=null;">
Incorrect example
<!-- No fallback – a broken image leaves an empty alt box -->
<img src="data:image/png;base64,broken!!truncated==" alt="Missing icon">

Optimize and compress images before encoding

Downscale and compress raster images before converting them to base64. Smaller payloads reduce the risk of truncation, lower HTML transfer size, and improve LCP by shrinking the critical resource. A 120×120 px WebP is typically under 3 KB when base64-encoded; an uncompressed 2000×2000 PNG can exceed 3 MB.

Correct example – optimized payload
<!-- Small WebP icon (~2 KB base64) – fast to decode -->
<img src="data:image/webp;base64,UklGRhgCAABXRUJQVlA4WAoAAAAQAAAADwAADwAAQUxQSLAFAAABoUAIaNqP" alt="Tiny icon">
Incorrect example – oversized payload
<!-- Large uncompressed PNG encoded as data URL (~1.5 MB) -->
<!-- This bloats the HTML and can cause decoding timeouts on mobile -->
<img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAB4AAAAQ4CAMAAAAqEnG9AAAAD1BMVEUAAAD///8AAAAAAAAAAABAz/DAAAAAA..." alt="Large photo">

Known Limitations

  • Dynamic DOM manipulation – Single-page applications (SPAs) and frameworks (React, Angular, Vue) may inject <img> elements with data URLs after the rule has finished scanning. A re-scan is required to catch late-added images.
  • Shadow DOM – Images nested inside closed shadow roots are not traversed unless the rule is explicitly configured with mode: 'open' or a specialized shadow-DOM walker.
  • Background images – The rule only inspects <img> elements. CSS background-image: url(data:…) declarations and SVG <image> elements with data URLs are not validated.
  • iframe contexts – Images inside cross-origin iframes are inaccessible due to the same-origin policy and fall outside the rule’s scope.
  • Very large data URLs – Extremely long data URL strings (over several MB) may cause the regex validation to match slowly or produce false negatives if truncated by the browser’s internal limits.
  • Browser decoding edge cases – naturalWidth === 0 && complete may produce false negatives for certain animated image formats or progressive-decoded JPEGs on some browser versions.

Resources

Rule

  • Audit: performance
  • Standard: SiteLint
  • Level: Best practices
  • Success Criteria: N/A
  • Rule ID: broken-data-url-image