{"record":{"id":"6efbc60a74bb6d1a","repo":"remix-run/remix","slug":"file-transform-failed","errorCode":"FILE_TRANSFORM_FAILED","errorMessage":"${formatFileTransformSubject(transformSubject)} failed for ${filePath}. ${formatUnknownError(error)}","messagePattern":"(.+?) failed for (.+?)\\. (.+?)","errorType":"error_code","errorClass":"AssetServerCompilationError","httpStatus":null,"severity":"error","filePath":"packages/assets/src/lib/files/compiler.ts","lineNumber":776,"sourceCode":"      { code: 'FILE_TRANSFORM_RESULT_INVALID' },\n    )\n  }\n\n  return normalizedExtension\n}\n\nfunction toFileTransformFailedError(\n  error: unknown,\n  filePath: string,\n  transformSubject: FileTransformSubject,\n): AssetServerCompilationError {\n  if (isAssetServerCompilationError(error)) return error\n\n  return createAssetServerCompilationError(\n    `${formatFileTransformSubject(transformSubject)} failed for ${filePath}. ${formatUnknownError(error)}`,\n    {\n      cause: error,\n      code: 'FILE_TRANSFORM_FAILED',\n    },\n  )\n}\n\nfunction getGlobalFileTransformSubject(\n  globalTransform: FileCompilerOptions['globalTransforms'][number],\n  index: number,\n): FileTransformSubject {\n  let functionName = globalTransform.transform.name\n  return {\n    index,\n    kind: 'global',\n    name: globalTransform.name ?? (functionName.length > 0 ? functionName : undefined),\n  }\n}\n\nfunction formatFileTransformSubject(transformSubject: FileTransformSubject): string {\n  if (transformSubject.kind === 'request') {","sourceCodeStart":758,"sourceCodeEnd":794,"githubUrl":"https://github.com/remix-run/remix/blob/9696913134be3a4423513d2775f7b31d6917c049/packages/assets/src/lib/files/compiler.ts#L758-L794","documentation":"This is the wrapper that runs user-supplied file transforms (per-file or global): if the transform throws or its promise rejects, the error is rewrapped into an AssetServerCompilationError with code FILE_TRANSFORM_FAILED, preserving the original as `cause` and appending its formatted message. Non-compilation errors from inside the transform always surface this way.","triggerScenarios":"Any exception inside a transform callback: JSON.parse failing on file content, fs read of a helper file missing, a TypeError from bad string manipulation, or a rejected async transform. The original error's message appears after 'failed for <filePath>'.","commonSituations":"Transforms assuming a specific file format (parsing CSS as JSON); missing optional dependencies in the transform's environment; file encoding surprises (binary file passed as string); runtime differences between dev and build environments.","solutions":["Read the appended original message and the `cause` to find the real failure inside your transform","Make the transform defensive: detect file types before parsing and pass unsupported files through unchanged","Wrap risky parsing in try/catch inside the transform and either return original content or throw a clearer domain error"],"exampleFix":"// before\ntransform: (content) => JSON.parse(content) // throws SyntaxError on non-JSON → FILE_TRANSFORM_FAILED\n\n// after\ntransform: (content, filePath) => {\n  if (!filePath.endsWith('.json')) return content\n  try {\n    return JSON.stringify(JSON.parse(content))\n  } catch (error) {\n    throw new Error(`Invalid JSON in ${filePath}: ${error.message}`)\n  }\n}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":"function isAssetServerCompilationError(error: unknown): error is { code: string; cause?: unknown } {\n  return !!error && typeof error === 'object' && 'code' in error && (error as any).code === 'FILE_TRANSFORM_FAILED'\n}","tryCatchPattern":"try {\n  await compileFiles(files, { transforms: [myTransform] })\n} catch (error) {\n  if (isAssetServerCompilationError(error)) {\n    console.error(`transform failed: ${error.cause?.message ?? error.message}`)\n    // fail the build with the underlying cause, or skip the file\n  }\n  throw error\n}","preventionTips":["Detect file types before parsing content inside transforms","Wrap risky parsing in try/catch and throw a clearer domain error","Test transforms against representative file fixtures including malformed ones"],"tags":["asset-server","file-transform","error-wrapping","cause"],"backgroundTag":"transform-callback-threw","analyzedSha":"9696913134be3a4423513d2775f7b31d6917c049","analyzedAt":"2026-08-27T19:55:01.024Z","schemaVersion":2},"datasetVersion":"2026-08-28T00:17:15.603Z"}