Resource loading: onload and onerror

A web page rarely arrives in one piece. Scripts, images, iframes, stylesheets — each is a separate download that finishes on its own schedule, and often after your code has already started running. The browser gives you two events to find out how each of those downloads went:

• load — the resource downloaded fine (and, for a script, ran to completion).
• error — the download failed.

Get a handle on these two and you can build reliable loading logic: run code the moment a library is ready, swap in a fallback image when one 404s, or report the failure to a monitoring service.

Loading a script

Say you want to pull in a third-party library at runtime and then call a function it defines. You can create the <script> element yourself and drop it into the document:

let script = document.createElement('script');
script.src = "my.js";

document.head.append(script);

The moment that element lands in the document, the browser starts fetching my.js. But the fetch is asynchronous. The next line of your code runs immediately, long before the download is done — so any function declared inside my.js does not exist yet. Call it too early and you get a ReferenceError.

You need a signal that says “the script is ready now.” That signal is the load event.

script.onload

The load event fires after the script has been downloaded and executed. By the time your handler runs, everything the script declared — variables, functions, globals — is available.

let script = document.createElement('script');

// can load any script, from any domain
script.src = "https://cdnjs.cloudflare.com/ajax/libs/mathjs/11.11.0/math.js"
document.head.append(script);

script.onload = function() {
  // the script has run, so its global "math" now exists
  alert( math.version ); // shows the library version
};

Inside onload you are on safe ground: reach for the library’s variables, call its functions, wire up the rest of your app that depended on it.

Watch the async gap for yourself. The demo below adds a <script> that defines a global confetti function. (A real page would point src at a URL; here the code is inlined as a data: source so nothing hits the network — the loading behavior is the same.) Notice how, right after append, the function still doesn’t exist — it only becomes callable once load fires:

<button id="sl-run">Load the script</button>
<pre id="sl-out">Press the button.</pre>

button{font:14px sans-serif;padding:8px 14px;border:1px solid #6d28d9;background:#6d28d9;color:#fff;border-radius:8px;cursor:pointer}
pre{background:#f4f4f5;border-radius:8px;padding:12px;white-space:pre-wrap;line-height:1.6;margin-top:12px}

const out = document.getElementById('sl-out');
const btn = document.getElementById('sl-run');

// A tiny "library" that just adds one global. Delivered as a script element.
const librarySource = "window.confetti = function(n){ return '\u{1F389}'.repeat(n); };";
const src = "data:text/javascript," + encodeURIComponent(librarySource);

btn.onclick = function() {
delete window.confetti;

const script = document.createElement('script');
script.src = src;

// set the handler BEFORE appending — tidy habit
script.onload = function() {
  out.textContent +=
    '\nload fired -> typeof confetti is now: ' + (typeof window.confetti) +
    '\nconfetti(3) = ' + window.confetti(3);
};
script.onerror = function() {
  out.textContent += '\nerror: the script failed to load';
};

document.head.append(script);

// this line runs immediately, long before the download finishes
out.textContent =
  'right after append -> typeof confetti: ' + (typeof window.confetti);
};

But what if the fetch never succeeds? Maybe the file is gone (a 404), maybe the server is unreachable. In that case load never fires — and you need the other event.

script.onerror

A failed download shows up as an error event. Point a script at a URL that doesn’t exist and watch it fire:

let script = document.createElement('script');
script.src = "https://example.com/404.js"; // no such script
document.head.append(script);

script.onerror = function() {
  alert("Error loading " + this.src); // Error loading https://example.com/404.js
};

One important limit: the error event tells you that the load failed, not why. You can’t read the HTTP status from it. A 404, a 500, a DNS failure, a dropped connection — they all surface as the same bare error event, with no status code attached. If you need the status, fetch is the right tool for the download instead.

The demo below makes that split concrete. The “Run clean code” button runs code that finishes without incident. The “Run buggy code” button runs code that calls a function that doesn’t exist — a runtime error that load/error would never surface. Only the global window.onerror handler hears about it:

<button id="oe-ok">Run clean code</button>
<button id="oe-throw">Run buggy code</button>
<pre id="oe-out">Nothing has run yet.</pre>

button{font:14px sans-serif;padding:8px 14px;border:1px solid #6d28d9;background:#fff;color:#6d28d9;border-radius:8px;cursor:pointer;margin-right:8px}
pre{background:#f4f4f5;border-radius:8px;padding:12px;white-space:pre-wrap;line-height:1.6;margin-top:12px}

const out = document.getElementById('oe-out');

// The global net for uncaught runtime errors.
window.onerror = function(message, url, line, col) {
out.textContent = 'window.onerror caught:\n' + message;
return true; // handled — suppress the default logging
};

document.getElementById('oe-ok').onclick = function() {
out.textContent = 'Ran fine. Nothing was thrown, so window.onerror stayed quiet.';
};

document.getElementById('oe-throw').onclick = function() {
out.textContent = 'Running buggy code...';
// Thrown asynchronously so it escapes as a genuine uncaught error.
setTimeout(function() {
  totallyUndefinedFunction();
}, 60);
};

Other resources

load and error aren’t special to scripts. They work for pretty much any element that pulls in an external file through a src — images, iframes, and more.

let img = document.createElement('img');
img.src = "https://example.com/media/skyline-poster.png"; // (*)

img.onload = function() {
  alert(`Image loaded, size ${img.width}x${img.height}`);
};

img.onerror = function() {
  alert("Error occurred while loading image");
};

Try both paths below. “Load a valid image” points at a real (inlined) picture and fires load; “Load a broken image” points at garbage data and fires error, at which point the handler swaps in a fallback — exactly the pattern you’d use to replace a 404’d image on a live page:

<button id="img-good">Load a valid image</button>
<button id="img-bad">Load a broken image</button>
<div id="img-box"></div>
<pre id="img-log">Pick a button.</pre>

button{font:14px sans-serif;padding:8px 14px;border:1px solid #6d28d9;background:#fff;color:#6d28d9;border-radius:8px;cursor:pointer;margin-right:8px;margin-bottom:10px}
#img-box{min-height:80px}
img{border-radius:8px;display:block}
.fallback{width:120px;height:80px;display:flex;align-items:center;justify-content:center;background:#fee2e2;color:#b91c1c;border-radius:8px;font:13px sans-serif;text-align:center}
pre{background:#f4f4f5;border-radius:8px;padding:12px;white-space:pre-wrap;line-height:1.6;margin-top:12px}

const box = document.getElementById('img-box');
const log = document.getElementById('img-log');

const good = "data:image/svg+xml," + encodeURIComponent(
"<svg xmlns='http://www.w3.org/2000/svg' width='120' height='80'>" +
"<rect width='120' height='80' rx='8' fill='#6d28d9'/>" +
"<text x='60' y='46' font-family='sans-serif' font-size='16' fill='white' text-anchor='middle'>hello</text></svg>"
);
const broken = "data:image/png;base64,this-is-not-valid-image-data";

function load(src, label) {
log.textContent = 'Loading ' + label + '...';
box.innerHTML = '';

const img = document.createElement('img');

img.onload = function() {
  log.textContent = 'load fired -> size ' + img.naturalWidth + 'x' + img.naturalHeight;
};
img.onerror = function() {
  log.textContent = 'error fired -> swapping in a fallback';
  box.innerHTML = '<div class="fallback">image<br>unavailable</div>';
};

img.src = src; // <img> starts loading the instant src is set
box.append(img);
}

document.getElementById('img-good').onclick = function() { load(good, 'a valid image'); };
document.getElementById('img-bad').onclick = function() { load(broken, 'a broken image'); };

A couple of quirks are worth carrying with you:

• Most resources begin loading when they’re added to the document. An <img> is the odd one out: it starts loading the moment it gets a src, marked (*) above — not when it’s inserted into the page. So an image can be fully loaded before it ever appears in the DOM.
• An <iframe> fires load no matter what. When an iframe finishes, iframe.onload triggers for both a successful page and a failed one. There’s no separate error path for it.

Both behaviors are historical. They predate any consistent design and are kept for backward compatibility.

Cross-origin policy

There’s a browser security rule underneath all of this: a script running on one site can’t read the contents of another site. A script on https://facebook.com has no business reading your inbox at https://gmail.com, and the browser makes sure it can’t.

More precisely, the boundary is the origin — the triplet of protocol, domain, and port. Change any one of the three and you’re on a different origin with no automatic access across the line. A subdomain is a different origin. The same host on another port is a different origin. http:// versus https:// is a different origin.

That same wall applies to resources you load from other domains. If you pull in a script from another origin and it throws an error, the browser hides the details from you.

Take a script error.js that does nothing but call a function that doesn’t exist:

// 📁 error.js
missingHelper();

Load it from the same site it lives on, with a global handler watching:

<script>
window.onerror = function(message, url, line, col, errorObj) {
  alert(`${message}\n${url}, ${line}:${col}`);
};
</script>
<script src="/js/error.js"></script>

You get a full, useful report — message, file, and exact position:

Uncaught ReferenceError: missingHelper is not defined
https://example.com/js/error.js, 1:1

Now load the identical script from a different domain:

<script>
window.onerror = function(message, url, line, col, errorObj) {
  alert(`${message}\n${url}, ${line}:${col}`);
};
</script>
<script src="https://another-domain.example.com/js/error.js"></script>

The report collapses to nothing:

Script error.
, 0:0

The exact wording varies by browser, but the meaning is fixed: any detail about a cross-origin script’s internals — the message, the line, the stack trace — is stripped out. That’s the origin boundary doing its job.

Why care about those details? Error-tracking services — the kind that listen on window.onerror, store every error your real users hit, and give you a dashboard to dig through them — are only as good as the data they receive. You can build one yourself. But when the failing code came from another origin and you didn’t opt into sharing, all your monitor records is a useless Script error.

The same cross-origin restriction (CORS) covers other resource types too, not just scripts.

To lift the veil, two things have to line up: the <script> tag needs a crossorigin attribute, and the remote server has to send the right response headers. One without the other isn’t enough.

There are three levels of access:

1. No crossorigin attribute — access prohibited. This is the default, and the reason you saw Script error. above.
2. crossorigin="anonymous" — access allowed if the server responds with Access-Control-Allow-Origin set to * or to your exact origin. The browser sends no cookies or HTTP auth to the remote server.
3. crossorigin="use-credentials" — access allowed if the server sends Access-Control-Allow-Origin with your origin and Access-Control-Allow-Credentials: true. The browser does send cookies and HTTP auth along.

In the failing example, there was no crossorigin attribute at all, so access was blocked. Add one and things change. If you don’t need cookies sent along, "anonymous" is the simplest choice — it needs just the one server header:

<script>
window.onerror = function(message, url, line, col, errorObj) {
  alert(`${message}\n${url}, ${line}:${col}`);
};
</script>
<script crossorigin="anonymous" src="https://another-domain.example.com/js/error.js"></script>

As long as the server sends back an Access-Control-Allow-Origin header, the browser now trusts the cross-origin relationship and hands you the full error report again.

Summary

Images, external stylesheets, scripts, and most other resources loaded through a src give you two events to track their download:

• load fires on a successful load.
• error fires on a failed one.

Remember the distinctions that trip people up:

• An <img> starts loading when it gets a src, not when it’s added to the page.
• An <iframe> only ever fires load — for both success and failure — so you can’t use error to detect a broken iframe.
• load/error report on the download. A script that loads fine but throws at runtime still fires load; catch those runtime errors with window.onerror.
• For cross-origin scripts, error details are hidden unless the tag carries crossorigin and the server sends the matching CORS header.

The older readystatechange event works on resources as well, but you’ll rarely reach for it — load and error cover the same ground with far less ceremony.