{"record":{"id":"5e110fa268ed2ef0","repo":"remotion-dev/remotion","slug":"string-refs-are-not-supported","errorCode":null,"errorMessage":"string refs are not supported","messagePattern":"string refs are not supported","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/core/src/video/html5-video.tsx","lineNumber":60,"sourceCode":"\t\tonAutoPlayError,\n\t\tonVideoFrame,\n\t\t...otherProps\n\t} = props;\n\tconst {loop, ...propsOtherThanLoop} = props;\n\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'<Html5Video> is not supported in @remotion/web-renderer. Use <Video> from @remotion/media instead. See https://remotion.dev/docs/client-side-rendering/limitations',\n\t\t);\n\t}\n\n\tconst {durations, setDurations} = useContext(DurationsContext);\n\n\tif (typeof ref === 'string') {\n\t\tthrow new Error('string refs are not supported');\n\t}\n\n\tif (typeof props.src !== 'string') {\n\t\tthrow new TypeError(\n\t\t\t`The \\`<Html5Video>\\` 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 onDuration = useCallback(\n\t\t(src: string, durationInSeconds: number) => {\n\t\t\tsetDurations({type: 'got-duration', durationInSeconds, src});\n\t\t},\n\t\t[setDurations],\n\t);","sourceCodeStart":42,"sourceCodeEnd":78,"githubUrl":"https://github.com/remotion-dev/remotion/blob/78fe4bb3fdb5a2cd68724393d63cb223db333fa7/packages/core/src/video/html5-video.tsx#L42-L78","documentation":"Thrown by Html5Video when the `ref` passed to the component is a string. Legacy React string refs (`ref=\"myVideo\"`) are not supported by Remotion's video components, which expect either a callback ref or a RefObject. The check runs on every render after the CSR guard.","triggerScenarios":"Passing a string ref to <Html5Video> (or <Video> that forwards to it): `<Html5Video ref=\"player\" />`. This legacy ref API was removed from modern React and Remotion explicitly rejects it.","commonSituations":"Copying old React tutorials that use string refs; upgrading a codebase from React 15-era patterns; using a ref string by accident when intending a callback or useRef value.","solutions":["Switch to a RefObject via useRef: `const ref = useRef<HTMLVideoElement>(null); <Html5Video ref={ref} />`.","Or use a callback ref: `ref={(el) => { videoEl = el; }}`."],"exampleFix":"// before\n<Html5Video ref=\"myVideo\" src={src} />\n\n// after\nconst videoRef = useRef<HTMLVideoElement>(null);\n<Html5Video ref={videoRef} src={src} />","handlingStrategy":"type-guard","validationCode":"import type {Ref} from 'react';\n\nconst isStringRef = (ref: unknown): ref is string => typeof ref === 'string';\nif (isStringRef(ref)) throw new Error('use a RefObject or callback ref');","typeGuard":"const isSupportedRef = (ref: unknown): boolean =>\n  typeof ref !== 'string';","tryCatchPattern":null,"preventionTips":["Never pass string refs to Remotion components; use useRef or a callback ref.","Enable React strict mode / legacy-ref lint rules to catch string refs."],"tags":["video","react","refs","api-misuse"],"backgroundTag":null,"analyzedSha":"78fe4bb3fdb5a2cd68724393d63cb223db333fa7","analyzedAt":"2026-08-12T17:18:50.444Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}