{"record":{"id":"59f066db7044734e","repo":"remotion-dev/remotion","slug":"getimagedimensions-is-only-available-in-the-brow","errorCode":null,"errorMessage":"getImageDimensions() is only available in the browser.","messagePattern":"getImageDimensions\\(\\) is only available in the browser\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/media-utils/src/get-image-dimensions.ts","lineNumber":14,"sourceCode":"import {pLimit} from './p-limit';\nimport type {ImageDimensions} from './types';\n\nconst imageDimensionsCache: {[key: string]: ImageDimensions} = {};\n\nconst limit = pLimit(3);\n\nconst fn = async (src: string): Promise<ImageDimensions> => {\n\tif (imageDimensionsCache[src]) {\n\t\treturn imageDimensionsCache[src];\n\t}\n\n\tif (typeof document === 'undefined') {\n\t\tthrow new Error('getImageDimensions() is only available in the browser.');\n\t}\n\n\tconst imageDimensions = await new Promise<ImageDimensions>(\n\t\t(resolved, reject) => {\n\t\t\tconst image = new Image();\n\n\t\t\timage.onload = () => {\n\t\t\t\tconst {width, height} = image;\n\t\t\t\tresolved({width, height});\n\t\t\t};\n\n\t\t\timage.onerror = reject;\n\n\t\t\timage.src = src;\n\t\t},\n\t);\n\n\timageDimensionsCache[src] = imageDimensions;","sourceCodeStart":1,"sourceCodeEnd":32,"githubUrl":"https://github.com/remotion-dev/remotion/blob/78fe4bb3fdb5a2cd68724393d63cb223db333fa7/packages/media-utils/src/get-image-dimensions.ts#L1-L32","documentation":"Thrown by getImageDimensions() when `document` is undefined (line 14). The function constructs a DOM `Image()` and waits for onload to read width/height, so it requires a browser environment.","triggerScenarios":"Calling getImageDimensions() during SSR, in a Node build step, in Node-based tests, or in any non-browser runtime; calling it at module top level so it runs at import time on the server.","commonSituations":"Computing layout dimensions for images at build time; Next.js getStaticProps trying to size remote images; server-side rendered galleries; CI scripts that try to inspect image dimensions for validation.","solutions":["Call getImageDimensions() only inside Remotion components or other client code that runs in a browser.","For server-side dimension reads, use a Node image library (e.g. sharp, image-size, probe-image-size) instead of this DOM-based helper.","In tests, set the environment to jsdom/happy-dom or load a real image asset the polyfill can decode.","Guard the call site with typeof document !== 'undefined' to skip it during SSR."],"exampleFix":"// before (throws in Node SSR)\nimport {getImageDimensions} from '@remotion/media-utils';\nexport async function getStaticProps() {\n  const dims = await getImageDimensions('/hero.png');\n  return {props: {dims}};\n}\n\n// after (server uses sharp; client keeps the hook)\n// server\nimport sharp from 'sharp';\nconst {width, height} = await sharp(file).metadata();\n// client (Remotion)\nconst dims = await getImageDimensions(staticFile('hero.png'));","handlingStrategy":"validation","validationCode":"import {getImageDimensions} from '@remotion/media-utils';\n\nasync function safeGetImageDimensions(src: string) {\n  if (typeof document === 'undefined') {\n    // server-side: prefer sharp/probe-image-size here\n    return null;\n  }\n  return getImageDimensions(src);\n}","typeGuard":"const canUseDomImage = (): boolean => typeof document !== 'undefined' && typeof Image !== 'undefined';","tryCatchPattern":"try {\n  const dims = await getImageDimensions(src);\n} catch (err) {\n  if ((err as Error).message.includes('only available in the browser')) {\n    // server path: use sharp/probe-image-size instead\n  } else {\n    throw err;\n  }\n}","preventionTips":["Keep this helper inside Remotion components; use sharp or image-size for server-side dimension reads.","Guard isomorphic code with typeof document !== 'undefined'.","In Node tests, run under jsdom/happy-dom or stub the Image constructor.","Do not invoke this helper during build-time data fetching."],"tags":["browser-only","ssr","dom","image","environment"],"backgroundTag":null,"analyzedSha":"78fe4bb3fdb5a2cd68724393d63cb223db333fa7","analyzedAt":"2026-08-12T17:18:50.444Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}