remix-run/remix · error · TypeError

Expected a file path or file:// URL, received "${filePath}"

Error message

Expected a file path or file:// URL, received "${filePath}"

What it means

`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.

Source

Thrown at packages/assets/src/lib/files/compiler.ts:220

    isServedFilePath(filePath) {
      return isServedFilePath(filePath, resolvedOptions.extensionSet)
    },
    validateTransformQuery(transformQuery) {
      parseRequestTransforms(
        transformQuery,
        resolvedOptions.transforms,
        resolvedOptions.maxRequestTransforms,
      )
    },
  }

  function resolveInputFilePath(filePath: string): string {
    if (filePath.startsWith('file://')) {
      return normalizeFilePath(fileURLToPath(new URL(filePath)))
    }

    if (filePath.includes('://')) {
      throw new TypeError(`Expected a file path or file:// URL, received "${filePath}"`)
    }

    return resolveFilePath(resolvedOptions.rootDir, filePath)
  }

  function shouldUseTransformPipeline(transformQuery: readonly string[] | null): boolean {
    return (
      (transformQuery !== null && transformQuery.length > 0) ||
      resolvedOptions.globalTransforms.length > 0
    )
  }

  function getFreshSourceFileRecord(identityPath: string): SourceFileRecord {
    let record = sourceFileStore.get(identityPath)
    if (record.metadataSnapshot && !isFileSnapshotFresh(record.metadataSnapshot)) {
      sourceFileStore.invalidate(identityPath)
      clearTransformedCacheIndex(identityPath)
      record = sourceFileStore.get(identityPath)

View on GitHub (pinned to 9696913134)

Solutions

1. Download the resource to a local file and pass its path or `file://` URL instead
2. 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`)
3. Use `pathToFileURL(filePath).href` to build a valid file:// URL

Example fix

// before
resolvedFile('https://cdn.example.com/styles.css')
// after
let local = await downloadToTemp(url)
resolvedFile(pathToFileURL(local).href)

function isLocalFileRef(input: string): boolean {
  return input.startsWith('file://') || !input.includes('://')
}

function isFileUrlOrPath(v: string): boolean {
  return v.startsWith('file://') || !v.includes('://')
}

try {
  resolvedFile(input)
} catch (err) {
  if (err instanceof TypeError && err.message.includes('Expected a file path or file:// URL')) {
    // fetch remote resource to a temp file, then retry with pathToFileURL(temp).href
  } else throw err
}

When it happens

Trigger: 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.

Common situations: 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).

Related errors

• Expected a file path or file:// URL, received "${filePath}"
• Expected a file path or file:// URL, received "${filePath}"
• hmr must create a channel with a close function
• hmr must create a channel with an onFileEvents function
• hmr must create a channel with an updateWatchedFiles functio

AI-assisted analysis of remix-run/remix@9696913134 (2026-08-27). Data as JSON: /api/errors/8e10a1d53a094468. Report an issue: GitHub.