evanw/esbuild · error · Error

The input to "transform" must be a string or a Uint8Array

Error message

The input to "transform" must be a string or a Uint8Array

What it means

Error "The input to "transform" must be a string or a Uint8Array" thrown in evanw/esbuild.

Source

Thrown at lib/shared/common.ts:708

    // Ideally the "transform()" API would be faster than calling "build()"
    // since it doesn't need to touch the file system. However, performance
    // measurements with large files on macOS indicate that sending the data
    // over the stdio pipe can be 2x slower than just using a temporary file.
    //
    // This appears to be an OS limitation. Both the JavaScript and Go code
    // are using large buffers but the pipe only writes data in 8kb chunks.
    // An investigation seems to indicate that this number is hard-coded into
    // the OS source code. Presumably files are faster because the OS uses
    // a larger chunk size, or maybe even reads everything in one syscall.
    //
    // The cross-over size where this starts to be faster is around 1mb on
    // my machine. In that case, this code tries to use a temporary file if
    // possible but falls back to sending the data over the stdio pipe if
    // that doesn't work.
    let start = (inputPath: string | null) => {
      try {
        if (typeof input !== 'string' && !(input instanceof Uint8Array))
          throw new Error('The input to "transform" must be a string or a Uint8Array')
        let {
          flags,
          mangleCache,
        } = flagsForTransformOptions(callName, options, isTTY, transformLogLevelDefault)
        let request: protocol.TransformRequest = {
          command: 'transform',
          flags,
          inputFS: inputPath !== null,
          input: inputPath !== null ? protocol.encodeUTF8(inputPath)
            : typeof input === 'string' ? protocol.encodeUTF8(input)
              : input,
        }
        if (mangleCache) request.mangleCache = mangleCache
        sendRequest<protocol.TransformRequest, protocol.TransformResponse>(refs, request, (error, response) => {
          if (error) return callback(new Error(error), null)
          let errors = replaceDetailsInMessages(response!.errors, details)
          let warnings = replaceDetailsInMessages(response!.warnings, details)
          let outstanding = 1

View on GitHub (pinned to 6ff1d8b0d8)

Solutions

1. Pass a string or Uint8Array as the first argument to "transform"
2. Read file contents yourself and pass the string/bytes instead of a path or other type

Example fix

const result = await esbuild.transform('let x: number = 1', { loader: 'ts' });

When it happens

Trigger: Thrown at lib/shared/common.ts:708 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of evanw/esbuild@6ff1d8b0d8 (2026-08-03). Data as JSON: /data/errors/4f65b072257b6cfa.json. Report an issue: GitHub.