Handling SRI Hash Mismatch Errors

Debugging SRI Hash Mismatch Errors

When the browser's computed hash does not match the integrity attribute value, the resource is blocked and an error is logged. Understanding why mismatches occur and how to handle them gracefully is critical for maintaining site reliability.

Common Causes of Hash Mismatches

1. CDN updated the file — if you use a non-pinned version URL (e.g., lib@3 instead of lib@3.2.1), the CDN may serve a newer version
2. Encoding differences — the file was saved with a different encoding (UTF-8 vs. UTF-8 with BOM) or line ending (LF vs. CRLF)
3. CDN compression — some CDNs modify whitespace or add tracking comments; the hash must match the delivered content
4. Wrong hash — a copy-paste error in the integrity attribute value
5. Cache poisoning — a proxy or CDN cache serves a stale or corrupted version
6. Legitimate attack — the file was actually tampered with (SRI is working as intended)

Console Error Messages

Browsers report SRI failures in the developer console:

Failed to find a valid digest in the 'integrity'
attribute for resource 'https://cdn.example.com/lib.js'
with computed SHA-384 integrity 'sha384-actual...'.
The resource has been blocked.

Implementing Graceful Fallbacks

<script
  src="https://cdn.example.com/lib.js"
  integrity="sha384-..."
  crossorigin="anonymous"
  onerror="loadLocalFallback('lib')"
></script>

<script>
function loadLocalFallback(name) {
  const script = document.createElement('script');
  script.src = '/fallback/' + name + '.js';
  // Same-origin fallback does not need integrity
  document.head.appendChild(script);
  // Log the incident
  navigator.sendBeacon('/api/sri-failure', JSON.stringify({
    resource: name,
    timestamp: Date.now()
  }));
}
</script>

Monitoring SRI Failures

In production, monitor SRI failures to distinguish between:

• Transient issues: CDN cache propagation delays (resolve within minutes)
• Persistent issues: Wrong hash in your HTML (fix and redeploy)
• Security incidents: Actual file tampering (investigate immediately)

Debugging Steps

1. Open the browser console and find the SRI error message
2. Note the computed hash from the error message
3. Compare it with the hash in your HTML
4. Download the file and compute the hash locally
5. Check for encoding, whitespace, or BOM differences
6. Verify the CDN URL is pinned to an exact version
7. Test with a fresh browser (no cache, no extensions)

Prevention

• Always pin exact versions in CDN URLs
• Regenerate hashes during every dependency upgrade
• Automate hash generation in your build pipeline
• Test SRI in staging before production deployment