jestjs/jest · error · Error

● Invalid return value: `process()` or/and `processAsync()

Error message

● Invalid return value:
  `process()` or/and `processAsync()` method of code transformer found at 
  "${slash(transformPath)}" 
  should return an object or a Promise resolving to an object. The object 
  must have `code` property with a string of processed code.

  This error may be caused by a breaking change in Jest 28:
  https://jest-archive-august-2023.netlify.app/docs/28.x/upgrading-to-jest28#transformer
  Code Transformation Documentation:
  https://jestjs.io/docs/code-transformation

What it means

Thrown by `_buildTransformResult` (ScriptTransformer.ts:401-408) via `makeInvalidReturnValueError` when a transformer's `process`/`processAsync` was called and returned a non-null value, but that value's `code` property is not a string. The transformer contract (`TransformedSource`) requires `{ code: string, map?: ... }`; returning the source string directly, an array, or an object without `code` triggers this.

Source

Thrown at packages/jest-transform/src/ScriptTransformer.ts:407

    content: string,
    transformer: Transformer | undefined,
    shouldCallTransform: boolean,
    options: ReducedTransformOptions,
    processed: TransformedSource | null,
    sourceMapPath: string | null,
  ): TransformResult {
    let transformed: TransformedSource = {
      code: content,
      map: null,
    };

    if (transformer && shouldCallTransform) {
      if (processed != null && typeof processed.code === 'string') {
        transformed = processed;
      } else {
        const transformPath = this._getTransformPath(filename);
        invariant(transformPath);
        throw new Error(makeInvalidReturnValueError(transformPath));
      }
    }

    if (transformed.map == null || transformed.map === '') {
      try {
        //Could be a potential freeze here.
        //See: https://github.com/jestjs/jest/pull/5177#discussion_r158883570
        const inlineSourceMap = sourcemapFromSource(transformed.code);
        if (inlineSourceMap) {
          transformed.map = inlineSourceMap.toObject() as FixedRawSourceMap;
        }
      } catch {
        const transformPath = this._getTransformPath(filename);
        invariant(transformPath);
        console.warn(makeInvalidSourceMapWarning(filename, transformPath));
      }
    }

View on GitHub (pinned to f49721c78e)

Solutions

Always return `{ code: <string>, map?: <sourceMap> }` from `process`/`processAsync`.
Read the linked Jest 28 upgrade guide and the `TransformedSource` type from `@jest/transform`.
Add a TypeScript return-type annotation (`: TransformedSource`) so the shape is checked at compile time.
For async transformers, `return { code: await compile(source) }` - never return the bare string promise.

Example fix

// before
module.exports = {
  process(source) { return compile(source); }, // returns a string
};
// after
module.exports = {
  process(source) { return { code: compile(source) }; },
};

Defensive patterns

Strategy: type-guard

Validate before calling

// Unit-test your transformer's return shape
const out = transformer.process('let x', 'fake.js', {});
if (out == null || typeof out.code !== 'string')
  throw new Error('process() must return { code: string }');

Type guard

const isTransformedSource = (v: any): boolean =>
  v != null && typeof v === 'object' && typeof v.code === 'string';

Prevention

Annotate `process(source, filename, options): TransformedSource` so the compiler enforces the shape.
Always return `{ code, map? }` - never a bare string or Promise<string>.
For async transformers, `return { code: await compile(src) }`.

When it happens

Trigger: A transformer that `return compile(source)` (string) instead of `return { code: compile(source) }`; returning `{ transformed: ... }` (wrong key); returning a Promise resolving to a string; returning `undefined` from a branch (`if (...) return;`).

Common situations: The headline Jest 28 upgrade breakage called out in the error text: pre-28 transformers returned `{ code, map }` but some returned just the code string; authors following an outdated guide; async transformer forgetting to await the compile and returning `Promise<string>`.

Related errors

AI-assisted analysis of jestjs/jest@f49721c78e (2026-08-03). Data as JSON: /data/errors/c9a4c0ceda70fdfb.json. Report an issue: GitHub.