{"record":{"id":"652aec684dfbf94d","repo":"remix-run/remix","slug":"file-transform-result-invalid","errorCode":"FILE_TRANSFORM_RESULT_INVALID","errorMessage":"${formatFileTransformSubject(options.transformSubject)} must return a string, Uint8Array, or object for ${options.filePath}","messagePattern":"(.+?) must return a string, Uint8Array, or object for (.+?)","errorType":"error_code","errorClass":"AssetServerCompilationError","httpStatus":null,"severity":"error","filePath":"packages/assets/src/lib/files/compiler.ts","lineNumber":710,"sourceCode":"): AssetFileTransformResult & { content: Uint8Array; extension: string } {\n  if (typeof result === 'string') {\n    return {\n      content: new TextEncoder().encode(result),\n      extension: options.currentExtension,\n    }\n  }\n\n  if (result instanceof Uint8Array) {\n    return {\n      content: result,\n      extension: options.currentExtension,\n    }\n  }\n\n  if (result === null || typeof result !== 'object') {\n    throw createAssetServerCompilationError(\n      `${formatFileTransformSubject(options.transformSubject)} must return a string, Uint8Array, or object for ${options.filePath}`,\n      { code: 'FILE_TRANSFORM_RESULT_INVALID' },\n    )\n  }\n\n  if (\n    !('content' in result) ||\n    (typeof result.content !== 'string' && !(result.content instanceof Uint8Array))\n  ) {\n    throw createAssetServerCompilationError(\n      `${formatFileTransformSubject(options.transformSubject)} must return a string or Uint8Array content value for ${options.filePath}`,\n      { code: 'FILE_TRANSFORM_RESULT_INVALID' },\n    )\n  }\n\n  let extension = options.currentExtension\n  if ('extension' in result && result.extension !== undefined) {\n    if (typeof result.extension !== 'string') {\n      throw createAssetServerCompilationError(\n        `${formatFileTransformSubject(options.transformSubject)} must return a string extension for ${options.filePath}`,","sourceCodeStart":692,"sourceCodeEnd":728,"githubUrl":"https://github.com/remix-run/remix/blob/9696913134be3a4423513d2775f7b31d6917c049/packages/assets/src/lib/files/compiler.ts#L692-L728","documentation":"A file transform (per-file or global) must return transformed content as a string, a Uint8Array, or a result object. After awaiting the transform, the compiler rejects any return value that is null or not an object when it expected the object form — i.e. the transform returned an unusable type such as a number, boolean, null, or undefined, failing with FILE_TRANSFORM_RESULT_INVALID.","triggerScenarios":"A transform function that returns undefined (falls off the end), returns null, or returns a primitive like a number; also returning a Buffer-like or stream object that isn't a Uint8Array or the expected object shape.","commonSituations":"Writing a transform with an early-return path that forgets to return content; returning `undefined` to mean 'no change' (this API does not support that — return the original content instead); async transforms whose promise resolves to nothing because of a missed return.","solutions":["Return the content explicitly: a string, a Uint8Array, or `{ content, extension? }`","For 'no change' paths, return the input content (or its bytes) rather than undefined/null","Add a unit test asserting every branch of the transform returns a value"],"exampleFix":"// before\ntransform: (content, filePath) => {\n  if (!filePath.endsWith('.md')) return // → undefined\n  return minify(content)\n}\n\n// after\ntransform: (content, filePath) => {\n  if (!filePath.endsWith('.md')) return content\n  return minify(content)\n}","handlingStrategy":"validation","validationCode":"function validateTransformResult(result: unknown): string | Uint8Array | { content: string | Uint8Array; extension?: string } {\n  if (typeof result === 'string' || result instanceof Uint8Array) return result\n  if (result && typeof result === 'object' && 'content' in result) return result as any\n  throw new TypeError('transform must return string, Uint8Array, or { content, extension? }')\n}\n\n// wrap your transform:\nconst safeTransform = (content, filePath) => validateTransformResult(myTransform(content, filePath))","typeGuard":"function isValidTransformResult(result: unknown): boolean {\n  return (\n    typeof result === 'string' ||\n    result instanceof Uint8Array ||\n    (!!result && typeof result === 'object')\n  )\n}","tryCatchPattern":null,"preventionTips":["Never let a transform branch return undefined — return original content instead","Unit-test every branch of custom transforms"],"tags":["asset-server","file-transform","validation","files"],"backgroundTag":"transform-invalid-return-value","analyzedSha":"9696913134be3a4423513d2775f7b31d6917c049","analyzedAt":"2026-08-27T19:55:01.024Z","schemaVersion":2},"datasetVersion":"2026-08-28T00:17:15.603Z"}