{"record":{"id":"bef2a2cc0e9183ee","repo":"remotion-dev/remotion","slug":"the-html5audio-tag-requires-a-string-for-src","errorCode":null,"errorMessage":"The `<Html5Audio>` tag requires a string for `src`, but got ${JSON.stringify(props.src)} instead.","messagePattern":"The `<Html5Audio>` tag requires a string for `src`, but got (.+?) instead\\.","errorType":"exception","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"packages/core/src/audio/html5-audio.tsx","lineNumber":68,"sourceCode":"\tconst {fps} = useVideoConfig();\n\tconst environment = useRemotionEnvironment();\n\tconst shouldPauseWhenBuffering = resolveV5Default(pauseWhenBuffering);\n\n\tif (environment.isClientSideRendering) {\n\t\tthrow new Error(\n\t\t\t'<Html5Audio> is not supported in @remotion/web-renderer. Use <Audio> from @remotion/media instead. See https://remotion.dev/docs/client-side-rendering/limitations',\n\t\t);\n\t}\n\n\tif (typeof freeze !== 'undefined') {\n\t\tthrow new TypeError(\n\t\t\t'The \"freeze\" prop is not supported on <Html5Audio />. Use <Sequence freeze={...}> to freeze media playback.',\n\t\t);\n\t}\n\n\tconst {durations, setDurations} = useContext(DurationsContext);\n\tif (typeof props.src !== 'string') {\n\t\tthrow new TypeError(\n\t\t\t`The \\`<Html5Audio>\\` tag requires a string for \\`src\\`, but got ${JSON.stringify(\n\t\t\t\tprops.src,\n\t\t\t)} instead.`,\n\t\t);\n\t}\n\n\tconst preloadedSrc = usePreload(props.src);\n\n\tconst onError: React.ReactEventHandler<HTMLAudioElement> = useCallback(\n\t\t(e) => {\n\t\t\t// eslint-disable-next-line no-console\n\t\t\tconsole.log(e.currentTarget.error);\n\n\t\t\t// If there is no `loop` property, we don't need to get the duration\n\t\t\t// and this does not need to be a fatal error\n\t\t\tconst errMessage = `Could not play audio with src ${preloadedSrc}: ${e.currentTarget.error}. See https://remotion.dev/docs/media-playback-error for help.`;\n\n\t\t\tif (loop) {","sourceCodeStart":50,"sourceCodeEnd":86,"githubUrl":"https://github.com/remotion-dev/remotion/blob/78fe4bb3fdb5a2cd68724393d63cb223db333fa7/packages/core/src/audio/html5-audio.tsx#L50-L86","documentation":"Html5Audio requires its src prop to be a plain string (a URL or static import path) so Remotion can preload, resolve, and track the media duration. Non-string values (undefined, number, object, React element) are rejected because the underlying <audio> tag and the duration-tracking context both depend on a resolvable string URL.","triggerScenarios":"Passing <Html5Audio src={undefined} />, src={0}, src={{url}}, src={<Img .../>}, or a conditional that evaluates to undefined/false. Also triggered by passing a staticFile() result wrapped in an array or object, or by forgetting to pass src entirely.","commonSituations":"Forgetting the src prop; conditional src that short-circuits to undefined when data hasn't loaded; migrating from <Audio> where src typing was looser; passing a remote object instead of its URL field.","solutions":["Ensure src is always a string: <Html5Audio src={typeof src === 'string' ? src : ''} /> or guard rendering with {src && <Html5Audio src={src} />}.","If loading asynchronously, delay mounting Html5Audio until the URL is resolved (use delayRender/continueRender or a conditional render).","Pass staticFile('audio.mp3') or a literal URL string directly."],"exampleFix":"// before\n<Html5Audio src={data?.audio} />\n\n// after\n{data?.audio ? <Html5Audio src={data.audio} /> : null}","handlingStrategy":"validation","validationCode":"if (typeof src !== 'string' || src.length === 0) {\n  // skip mounting or provide a default URL\n  return null;\n}","typeGuard":"const isValidAudioSrc = (src: unknown): src is string =>\n  typeof src === 'string' && src.length > 0;","tryCatchPattern":null,"preventionTips":["Type the src prop of your wrapper component as `string` (not string | undefined).","Render <Html5Audio> conditionally only after the URL is resolved.","Use delayRender to block rendering until async sources are ready."],"tags":["audio","props","validation","typescript","html5-audio"],"backgroundTag":null,"analyzedSha":"78fe4bb3fdb5a2cd68724393d63cb223db333fa7","analyzedAt":"2026-08-12T17:18:50.444Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}