{"record":{"id":"46f045220c95f94a","repo":"remix-run/remix","slug":"file-outside-mounts-46f045","errorCode":"FILE_OUTSIDE_MOUNTS","errorMessage":"File ${record.identityPath} is outside all configured mounts.","messagePattern":"File (.+?) is outside all configured mounts\\.","errorType":"error_code","errorClass":"AssetServerCompilationError","httpStatus":null,"severity":"error","filePath":"packages/assets/src/lib/scripts/transform.ts","lineNumber":230,"sourceCode":"        },\n      }\n    }\n    return {\n      ok: false,\n      error: toTransformFailedError(error, resolvedPath),\n      tracking: {\n        trackedFiles,\n      },\n    }\n  }\n\n  try {\n    let stableUrlPathname = args.routes.toUrlPathname(record.identityPath)\n    if (!stableUrlPathname) {\n      throw createAssetServerCompilationError(\n        `File ${record.identityPath} is outside all configured mounts.`,\n        {\n          code: 'FILE_OUTSIDE_MOUNTS',\n        },\n      )\n    }\n\n    let analysis = await analyzeModuleSource(sourceText, resolvedPath, transformOptions, {\n      define: args.define ?? undefined,\n      minify: args.minify,\n      loaders: args.loaders,\n      moduleUrl: stableUrlPathname,\n      sourceMaps: args.sourceMaps ?? undefined,\n      target: args.target ?? undefined,\n    })\n\n    analysis.unresolvedImports = analysis.unresolvedImports.filter(\n      (unresolved) => !args.externalSet.has(getDisplayImportSpecifier(unresolved.specifier)),\n    )\n\n    if (mayContainCommonJSModuleGlobals(sourceText) && isCommonJS(analysis.rawCode)) {","sourceCodeStart":212,"sourceCodeEnd":248,"githubUrl":"https://github.com/remix-run/remix/blob/9696913134be3a4423513d2775f7b31d6917c049/packages/assets/src/lib/scripts/transform.ts#L212-L248","documentation":"The asset transform pipeline maps each module's identity path to a stable URL pathname via the configured route mounts. When `args.routes.toUrlPathname(record.identityPath)` returns a falsy value, the file cannot be attributed to any mount, so the transform aborts with FILE_OUTSIDE_MOUNTS. This protects the asset server from serving modules whose URL identity cannot be resolved.","triggerScenarios":"Calling transformModule (directly or via transformModuleResult) for a record whose identityPath is not covered by any mount configured on the routes object. This happens when the file lives outside directories registered as mounts, or when routes.toUrlPathname returns undefined/null/'' for that path.","commonSituations":"Adding new source directories (e.g. a workspace package or vendor folder) without registering a corresponding mount; typos or case-mismatch in mount paths; moving files outside the app source root; custom routes implementations that only map routes/ but not shared lib directories.","solutions":["Check which mounts your routes/mount configuration defines and add an entry that covers the failing identityPath","Verify the file's absolute path (record.identityPath) against the mount prefixes — look for case sensitivity or symlink mismatches","If the file is intentionally outside mounts (e.g. node_modules or generated assets), exclude it from the transform set instead of mounting it","Ensure a custom toUrlPathname implementation returns a pathname for every record you pass to transformModule"],"exampleFix":"// before\nroutes.toUrlPathname('/packages/ui/src/button.ts') // => undefined → error\n\n// after\n// register the packages/ui directory as a mount so its files resolve to stable URLs\nmounts: [{ root: path.resolve('packages/ui'), prefix: '/ui' }]","handlingStrategy":"validation","validationCode":"const url = args.routes.toUrlPathname(record.identityPath)\nif (!url) {\n  throw new Error(`Refusing to transform ${record.identityPath}: not under any mount`)\n}","typeGuard":"function isInsideMounts(identityPath: string, routes: { toUrlPathname(p: string): string | undefined }): boolean {\n  return Boolean(routes.toUrlPathname(identityPath))\n}","tryCatchPattern":"catch (e) { if (isAssetServerCompilationError(e) && e.code === 'FILE_OUTSIDE_MOUNTS') { /* skip file or register mount */ } else throw e }","preventionTips":["Keep every transformed directory covered by an explicit mount entry","Run a preflight loop asserting toUrlPathname is truthy for all records before transforming","Fail fast in custom routes implementations with a descriptive error instead of returning undefined"],"tags":["assets","mounts","routing","build"],"backgroundTag":"path-outside-configured-root","analyzedSha":"9696913134be3a4423513d2775f7b31d6917c049","analyzedAt":"2026-08-27T19:55:01.024Z","schemaVersion":2},"datasetVersion":"2026-08-28T00:17:15.603Z"}