Cannot serialize arguments for

Error message

Cannot serialize arguments for {constructor} as json: {exn}

What it means

After resolving the constructor, Beam serializes the transform's args/kwargs to a JSON config for cross-language/spec representation. If json.dumps raises TypeError (non-JSON-serializable argument like a custom object, datetime, or set), it warns 'Cannot serialize arguments for <constructor> as json: <exn>' and returns the transform without the annotation.

Solutions

Convert arguments to JSON-serializable types: str for datetimes, float/int for Decimals and numpy scalars, lists for sets.
Pass primitives (str/int/float/bool/list/dict) instead of custom config objects.
Pre-serialize complex values yourself (e.g. json.dumps to a string) and parse them inside the transform.
Ignore the warning if the annotation is not required for your runner.

Example fix

// before
MyTransform(config=MyConfig(start=datetime.now()))
// after
MyTransform(config={'start': datetime.now().isoformat()})

Defensive patterns

Strategy: validation

Validate before calling

import json
def assert_jsonable(obj):
    try:
        json.dumps(obj)
    except TypeError as e:
        raise ValueError(f'argument not JSON-serializable: {e}')

Try / catch

import warnings
with warnings.catch_warnings():
    warnings.simplefilter('error')
    try:
        MyTransform(config=cfg)  # raises if config not JSON-serializable
    except TypeError as e:
        print(f'convert config to JSON types: {e}')

Prevention

Restrict ptransform arguments to JSON-native types
Serialize datetimes/Decimals to strings before passing
Add a unit test that json.dumps all pipeline configs

When it happens

Trigger: Passing arguments that are not JSON-serializable (datetime, Decimal, custom class instances, numpy scalars in some versions) to a ptransform whose configuration is being captured.

Common situations: Building pipelines with rich config objects in notebooks or scripts, then trying to export/specify them for remote runners or Beam YAML composition.

Understand the failure class

Background: "JSON serialization failed", "not JSON serializable", "Failed to serialize": why JSON marshaling errors happen and how to fix them — this error's family across 46 libraries.

Related errors

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/c2d55ac965fac50a. Report an issue: GitHub.

Appendix: source

Thrown at sdks/python/apache_beam/transforms/ptransform.py:1252

        f'{constructor.__module__}.{constructor.__qualname__}')
    try:
      imported_constructor = (
          python_callable.PythonCallableWithSource.
          load_from_fully_qualified_name(fully_qualified_name))
      if imported_constructor != wrapper:
        raise ImportError('Different object.')
    except ImportError:
      warnings.warn(f'Cannot import {constructor} as {fully_qualified_name}.')
      return transform

    try:
      config = json.dumps({
          'constructor': fully_qualified_name,
          'args': args,
          'kwargs': kwargs,
      })
    except TypeError as exn:
      warnings.warn(
          f'Cannot serialize arguments for {constructor} as json: {exn}')
      return transform

    original_annotations = transform.annotations
    transform.annotations = lambda: {
        **original_annotations(),
        # These override whatever may have been provided earlier.
        # The outermost call is expected to be the most specific.
        'yaml_provider': 'python',
        'yaml_type': 'PyTransform',
        'yaml_args': config, }
    return transform

  return wrapper

View on GitHub (pinned to 12126d8942)