A video with the autoplay attribute does not start
Uncaught (in promise) NotAllowedErrorShort answer
Browsers block autoplay for video with sound unless the user has interacted with the site. The reliable fix is to mute the video and add autoplay and playsinline. If play() is called in code, handle its promise: a rejection named NotAllowedError means the browser refused, so show a play button. Iframes also need allow="autoplay".
Fix it fast
1Find out which cause you have
Call play() yourself and read the rejection. The error name tells you if autoplay policy is the cause.
video.play().catch(err => console.log(err.name, err.message));2Match what you see, then jump to its fix
- 1
play() rejects with NotAllowedErrorThe video has sound and the user has not interacted yetFix - 2
Muted autoplay works in Chrome but not in SafariSafari needs playsinlineFix - 3
Uncaught (in promise) NotAllowedError in the consoleplay() is called from code and the rejection is not handledFix - 4
Embedded player does not start although the same video works on its own pageThe video sits in an iframe without the autoplay permissionFix
- 1
What does the error look like?
Uncaught (in promise) NotAllowedErrorThe video loads but stays paused on the first frame
Cause 1 of 4
The video has sound and the user has not interacted yet
1Check
MDN lists the rules: audible media is blocked unless it is muted, the user has interacted with the site, the site is allowlisted, or a Permissions Policy grants it. Chrome documents that muted autoplay is always allowed.
navigator.getAutoplayPolicy('mediaelement') // 'allowed', 'allowed-muted' or 'disallowed'2Fix
Mute the video. In React, write muted and playsInline on the element.
<video src="/hero.mp4" autoPlay muted loop playsInline />3Verify
Hard reload the page. The video starts without a click.
navigator.getAutoplayPolicy('mediaelement')Confirmed by developer.mozilla.org
Cause 2 of 4
Safari needs playsinline
1Check
MDN says playsinline is required for autoplay in Safari.
grep -rn "<video" src/2Fix
Add the playsInline prop alongside muted and autoPlay.
<video autoPlay muted playsInline src="/hero.mp4" />3Verify
Open the page on iPhone Safari.
navigator.getAutoplayPolicy('mediaelement')Confirmed by developer.mozilla.org
Cause 3 of 4
play() is called from code and the rejection is not handled
1Check
MDN says play() returns a promise that rejects when playback is blocked. The error name to test is NotAllowedError.
grep -rn "\.play()" src/2Fix
Catch the rejection and show a play button the user can press.
videoRef.current.play().catch(err => {
if (err.name === 'NotAllowedError') setShowPlayButton(true);
});3Verify
Block autoplay in the browser site settings and reload. The button appears.
console.log('check showPlayButton state')Confirmed by developer.mozilla.org
Cause 4 of 4
The video sits in an iframe without the autoplay permission
1Check
MDN's Permissions Policy section says the autoplay directive defaults to self, so a cross-origin iframe needs permission from the embedding page.
grep -rn "<iframe" src/2Fix
Add the autoplay permission to the iframe's allow attribute.
<iframe src="https://example.com/player" allow="autoplay"></iframe>3Verify
Reload and watch the embedded video start.
console.log('reload')Confirmed by developer.mozilla.org
How do I stop it coming back?
- Ship background videos muted, with playsinline, and without an audio track if the video does not need sound.
- Always put a catch on play() and give users a visible play button.
- Check navigator.getAutoplayPolicy on load for sound-on players.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
- TaskvareA task and project-management suite: React on the web, Flutter on mobile, TypeScript underneath.
Related fixes
Web apps
Module not found for antd/dist/antd.less after upgrading to Ant Design 5
Module not found: Error: Can't resolve 'antd/dist/antd.less'
Ant Design 5 dropped Less and the bundled CSS file for CSS-in-JS, so antd/dist/antd.less no longer exists.
3 causes, each with a fixWeb apps
Astro Code component fails inside a React component
Astro components cannot be rendered directly via function call
Astro components such as Code only exist on the server and render static HTML.
2 causes, each with a fixWeb apps
React shows Attempted import error when importing a component or function
Attempted import error:
The build found the file but not the name you asked for.
2 causes, each with a fixWeb apps
How to catch and handle a 422 from Axios in a Redux thunk
action.error.message is 'Rejected' and action.payload is undefined
A 422 means the server read the request but cannot process its content, so repeating it unchanged fails again.
4 causes, each with a fixWeb apps
axios gets 429 Too Many Requests from a React app
429 (Too Many Requests)
A 429 comes from the server or an API gateway, not from axios: your client sent too many requests in a window.
4 causes, each with a fixWeb apps
Axios request is not cancelled when a React component unmounts
A cancelled request is logged as an error in the catch block
Axios cancels a request when you pass it an AbortSignal and later call abort() on its controller.
4 causes, each with a fix