{"record":{"id":"35fbffa75c993da9","repo":"remotion-dev/remotion","slug":"loadfont-requires-a-url-field-in-the-options-o","errorCode":null,"errorMessage":"loadFont() requires a \"url\" field in the options object, but received ${url === undefined ? 'undefined' : JSON.stringify(url)}. If you want to load a Google Font, use the @remotion/google-fonts package instead. See: https://www.remotion.dev/docs/google-fonts/load-font","messagePattern":"loadFont\\(\\) requires a \"url\" field in the options object, but received (.+?)\\. If you want to load a Google Font, use the @remotion/google-fonts package instead\\. See: https://www\\.remotion\\.dev/docs/google-fonts/load-font","errorType":"validation","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"packages/fonts/src/load-font.ts","lineNumber":45,"sourceCode":"\n\tconst {\n\t\tfamily,\n\t\turl,\n\t\tascentOverride,\n\t\tdescentOverride,\n\t\tdisplay,\n\t\tfeatureSettings,\n\t\tlineGapOverride,\n\t\tstretch,\n\t\tstyle,\n\t\tunicodeRange,\n\t\tweight,\n\t\tformat,\n\t\tvariant,\n\t} = options;\n\n\tif (typeof url !== 'string') {\n\t\tthrow new TypeError(\n\t\t\t`loadFont() requires a \"url\" field in the options object, but received ${url === undefined ? 'undefined' : JSON.stringify(url)}. If you want to load a Google Font, use the @remotion/google-fonts package instead. See: https://www.remotion.dev/docs/google-fonts/load-font`,\n\t\t);\n\t}\n\n\tconst waitForFont = delayRender(\n\t\t`Loading font ${family} (url: ${url}, format: ${format}, weight: ${weight}, style: ${style}, variant: ${variant}, ascentOverride: ${ascentOverride}, descentOverride: ${descentOverride}, display: ${display}, featureSettings: ${featureSettings}, lineGapOverride: ${lineGapOverride}, stretch: ${stretch}, unicodeRange: ${unicodeRange})`,\n\t);\n\ttry {\n\t\tconst fontFormat = format ?? getFontFormat(url);\n\t\tconst font = new FontFace(family, `url('${url}') format('${fontFormat}')`, {\n\t\t\tascentOverride,\n\t\t\tdescentOverride,\n\t\t\tdisplay,\n\t\t\tfeatureSettings,\n\t\t\tlineGapOverride,\n\t\t\tstretch,\n\t\t\tstyle,\n\t\t\tunicodeRange,","sourceCodeStart":27,"sourceCodeEnd":63,"githubUrl":"https://github.com/remotion-dev/remotion/blob/78fe4bb3fdb5a2cd68724393d63cb223db333fa7/packages/fonts/src/load-font.ts#L27-L63","documentation":"The `loadFont` function validates that the options object contains a `url` field of type string after the initial object-type check. If `url` is undefined, null, a number, or any non-string, it throws a TypeError showing the received value (via `JSON.stringify`). This runs before any font loading begins and before `delayRender` is called.","triggerScenarios":"Calling `loadFont({family: 'MyFont'})` (no `url`), `loadFont({family: 'MyFont', url: 123})`, or `loadFont({family: 'MyFont', url: null})`. Also triggered by a destructuring mistake that drops the `url` key.","commonSituations":"Misspelling the `url` key (e.g., `src` or `href`), building the options object dynamically and forgetting to set `url`, or passing a font config from external data where the URL field is absent.","solutions":["Add a `url` string field to the options object.","Check the spelling of the `url` key (it must be exactly `url`).","If building the options dynamically, validate the URL is set before calling `loadFont`."],"exampleFix":"// before\nloadFont({ family: 'MyFont' });\n\n// after\nloadFont({ family: 'MyFont', url: '/fonts/myfont.woff2' });","handlingStrategy":"type-guard","validationCode":"if (typeof options.url !== 'string' || options.url.length === 0) {\n  throw new TypeError('loadFont requires a string url field');\n}\nloadFont(options);","typeGuard":"const hasUrlString = (v: unknown): v is { url: string } =>\n  typeof v === 'object' &&\n  v !== null &&\n  'url' in v &&\n  typeof (v as { url: unknown }).url === 'string';","tryCatchPattern":null,"preventionTips":["Always include family and url as string fields in the options object.","Double-check key spelling (url, not src or href).","Validate dynamically-built options objects before calling loadFont."],"tags":["fonts","validation","typescript","load-font","api-misuse"],"backgroundTag":null,"analyzedSha":"78fe4bb3fdb5a2cd68724393d63cb223db333fa7","analyzedAt":"2026-08-12T17:18:50.444Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}