async or defer on a script tag — and why async breaks your site every other load

Your site has a chart. Two scripts are loaded: a charting library and your code that uses it. The AI suggested "speeding up loading" and added async to both:
<script async src="chart-library.js"></script>
<script async src="my-chart.js"></script>
Everything works for you. A friend opens the site on their phone — no chart. The console says Chart is not defined. They refresh — the chart is there. Again — gone.
Here's the thing. async runs scripts in the order they finished downloading, not the order they're written. Your file is small — sometimes it arrives first and calls a library that isn't there yet. A textbook race condition. Let's see how async differs from defer and when to use which.
What the browser does with no attributes
The basics first. The browser reads HTML top to bottom and builds the page. When it hits a plain <script src="...">, it stops. Downloads the file, runs it, and only then keeps reading the HTML.
Two problems. While the script downloads, the page is blank. And if the script sits in <head> and looks for a button with document.querySelector, it gets null — the button doesn't exist yet, the browser hasn't read that far.
async and defer solve the first problem the same way: the file downloads in parallel while the browser keeps building the page. But when the script runs — that's where they split.
Comparison on five criteria
1. When it runs.
async— as soon as it's downloaded. Even if the page is half-built: the browser pauses while it runs.defer— only once all the HTML has been read. The page is fully built.
2. Execution order.
async— first downloaded, first run. Order in the HTML doesn't matter.defer— strictly in the order the scripts appear in the HTML.
This is the key difference. Scripts that depend on each other must not use async.
3. Can it see page elements.
async— not guaranteed. It may run when half the page doesn't exist yet.defer— yes, always. All the HTML has been read;querySelectorwill find any button.
4. Relationship to the DOMContentLoaded event.
async— may run before it or after it. Subscribing to it from an async script is sometimes too late.defer— all defer scripts run beforeDOMContentLoaded. The event is guaranteed to still be ahead.
5. Does it work with inline code.
- Both attributes only work on scripts with
src. On a<script defer>with code inside the tag,deferis simply ignored. (The exception istype="module", more below.)
Which one is for whom
No fence-sitting: for your own code, use defer. It keeps the order, sees the whole page, and doesn't block loading. It's the safe default.
async is for scripts that depend on nothing and that nothing depends on. A visit counter, a chat widget, an ad pixel. They don't care what's around them, so let them start early. That's how an analytics script is usually added, for example.
A simple test: "if this script runs first on the page, will something break?" If yes — defer. If no — async is fine.
The broken example from the start is fixed with one word:
<script defer src="chart-library.js"></script>
<script defer src="my-chart.js"></script>
Now the library always runs first and the chart second.
How to catch the race yourself
An "every other time" bug barely reproduces on a fast computer. Make the browser behave like a slow phone:
- Open DevTools → the Network tab.
- Tick Disable cache — otherwise files arrive instantly from cache.
- In the speed list, pick Slow 4G or 3G.
- Reload the page five or six times in a row and watch the console.
If the is not defined error appears sometimes but not every time, it's a race caused by async. Switch to defer and repeat: the error should disappear completely.
What about type="module"
Modern bundlers (Vite, Next.js) load code as <script type="module">. These scripts behave like defer by default — no attribute needed. That's why you'll rarely see these problems in a Vite project.
They show up in plain HTML: a single-file landing page, an embedded third-party widget, a site builder with custom code. Exactly where AI likes to "speed things up" with async. More ways to make a page faster are in our guide on how to speed up your website.
What happens if I write both async and defer?
A modern browser runs the script as async. defer in that pair is a fallback for very old browsers. Don't write both: it makes the intent harder to read.
Why does it work for me but not for users?
On your own machine files load from cache or localhost — they arrive almost simultaneously and in a "lucky" order. On slow mobile internet the order changes. Errors that show up "every other time" almost always mean a race — check for async.
The AI Architect 2027 course: step by step from computer basics to your own app and first customers. 543 short lessons on your phone.





