{"record":{"id":"8e10a1d53a094468","repo":"remix-run/remix","slug":"expected-a-file-path-or-file-url-received-f","errorCode":null,"errorMessage":"Expected a file path or file:// URL, received \"${filePath}\"","messagePattern":"Expected a file path or file:// URL, received \"(.+?)\"","errorType":"validation","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"packages/assets/src/lib/files/compiler.ts","lineNumber":220,"sourceCode":"    isServedFilePath(filePath) {\n      return isServedFilePath(filePath, resolvedOptions.extensionSet)\n    },\n    validateTransformQuery(transformQuery) {\n      parseRequestTransforms(\n        transformQuery,\n        resolvedOptions.transforms,\n        resolvedOptions.maxRequestTransforms,\n      )\n    },\n  }\n\n  function resolveInputFilePath(filePath: string): string {\n    if (filePath.startsWith('file://')) {\n      return normalizeFilePath(fileURLToPath(new URL(filePath)))\n    }\n\n    if (filePath.includes('://')) {\n      throw new TypeError(`Expected a file path or file:// URL, received \"${filePath}\"`)\n    }\n\n    return resolveFilePath(resolvedOptions.rootDir, filePath)\n  }\n\n  function shouldUseTransformPipeline(transformQuery: readonly string[] | null): boolean {\n    return (\n      (transformQuery !== null && transformQuery.length > 0) ||\n      resolvedOptions.globalTransforms.length > 0\n    )\n  }\n\n  function getFreshSourceFileRecord(identityPath: string): SourceFileRecord {\n    let record = sourceFileStore.get(identityPath)\n    if (record.metadataSnapshot && !isFileSnapshotFresh(record.metadataSnapshot)) {\n      sourceFileStore.invalidate(identityPath)\n      clearTransformedCacheIndex(identityPath)\n      record = sourceFileStore.get(identityPath)","sourceCodeStart":202,"sourceCodeEnd":238,"githubUrl":"https://github.com/remix-run/remix/blob/9696913134be3a4423513d2775f7b31d6917c049/packages/assets/src/lib/files/compiler.ts#L202-L238","documentation":"`resolveInputFilePath` accepts either a plain filesystem path or a `file://` URL. Any other URL scheme (http://, https://, data:, etc.) is rejected because the compiler must read the file from local disk.","triggerScenarios":"Passing a remote URL like `https://cdn.example.com/mod.ts` or another scheme (e.g. `data:text/plain,...`) where a local file path or `file:///...` URL is expected.","commonSituations":"Feeding URLs from HTML/import-map sources or configs into the file compiler; passing an `http://` URL that worked with a URL-fetching pipeline; Windows paths containing `://` by accident (rare).","solutions":["Download the resource to a local file and pass its path or `file://` URL instead","If the input is meant to be local, check for a bug upstream that turned a path into a URL (e.g. `new URL(path, base).href`)","Use `pathToFileURL(filePath).href` to build a valid file:// URL"],"exampleFix":"// before\nresolvedFile('https://cdn.example.com/styles.css')\n// after\nlet local = await downloadToTemp(url)\nresolvedFile(pathToFileURL(local).href)","handlingStrategy":"type-guard","validationCode":"function isLocalFileRef(input: string): boolean {\n  return input.startsWith('file://') || !input.includes('://')\n}","typeGuard":"function isFileUrlOrPath(v: string): boolean {\n  return v.startsWith('file://') || !v.includes('://')\n}","tryCatchPattern":"try {\n  resolvedFile(input)\n} catch (err) {\n  if (err instanceof TypeError && err.message.includes('Expected a file path or file:// URL')) {\n    // fetch remote resource to a temp file, then retry with pathToFileURL(temp).href\n  } else throw err\n}","preventionTips":["Convert remote URLs to local files before invoking the compiler","Use pathToFileURL() to build file URLs rather than string concatenation"],"tags":["file-path","url","validation","compiler"],"backgroundTag":"unsupported-url-scheme","analyzedSha":"9696913134be3a4423513d2775f7b31d6917c049","analyzedAt":"2026-08-27T19:55:01.024Z","schemaVersion":2},"datasetVersion":"2026-08-28T00:17:15.603Z"}