Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Next.js and React

A video with the autoplay attribute does not start

ErrorUncaught (in promise) NotAllowedError

Short 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".

  • Applies to Chrome 140, Firefox 140, Safari 18, React 19
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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));
  2. 2Match what you see, then jump to its fix

    1. 1play() rejects with NotAllowedErrorThe video has sound and the user has not interacted yetFix
    2. 2Muted autoplay works in Chrome but not in SafariSafari needs playsinlineFix
    3. 3Uncaught (in promise) NotAllowedError in the consoleplay() is called from code and the rejection is not handledFix
    4. 4Embedded player does not start although the same video works on its own pageThe video sits in an iframe without the autoplay permissionFix

What does the error look like?

  • Uncaught (in promise) NotAllowedError
  • The 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

Did this fix it?

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

Did this fix it?

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

Did this fix it?

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

Did this fix it?

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:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.