apache/beam · error · ValueError

Javascript mapping functions are not supported because the…

Error message

Javascript mapping functions are not supported because the quickjs-ng library is not installed.

What it means

JavaScript mapping transforms in Beam YAML require the quickjs-ng runtime. This ValueError fires when the quickjs import resolved to None (library not installed), so no JS evaluation engine is available.

Solutions

1. Install the dependency: pip install quickjs-ng (or apache-beam with the appropriate extras).
2. Recreate the environment ensuring optional extras are included.
3. If quickjs cannot be installed, switch the mapping to language python or jinja.
4. Verify installation with: python -c "import quickjs".

Example fix

# before: pipeline fails, no JS support
# after: install then run
pip install quickjs-ng
# or switch config:
# language: javascript  ->  language: python
# expression: "row.x + 1"

try:
    import quickjs
    HAVE_JS = True
except ImportError:
    HAVE_JS = False
if using_js and not HAVE_JS: raise EnvironmentError('pip install quickjs-ng')

try:
    pipeline = build(js_config)
except ValueError as e:
    if 'quickjs-ng' in str(e):
        install('quickjs-ng') or switch to language python
    else:
        raise

When it happens

Trigger: Using a mapping transform with language javascript (or path/name-based JS UDF) when the quickjs-ng Python package is absent from the environment; detected in _expand_javascript_mapping_func when `quickjs is None`.

Common situations: Minimal/production installs that omitted the extras (e.g. missing apache-beam[yaml] extras); running in environments without the wheel for your platform; upgrades where an optional dependency was dropped.

Understand the failure class

Background: "X is not installed. Please install it with pip install Y": missing optional dependency errors — ImportError/ValueError raised when a library's optional extra was never installed — this error's family across 22 libraries.

Related errors

• Error evaluating javascript expression
• File " " is not a valid .js file.
• Ambiguous expression type (perhaps missing quoting?)
• Ambiguous expression type (perhaps missing quoting?)
• Can only use expressions on a schema'd input.

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

Appendix: source

Thrown at sdks/python/apache_beam/yaml/yaml_mapping.py:256

  elif isinstance(py_value, bytes):
    return py_value.decode('utf-8', errors='replace')
  elif isinstance(py_value, (datetime.datetime, datetime.date, datetime.time)):
    return {'__date__': True, 'value': py_value.isoformat()}
  elif isinstance(py_value, Decimal):
    return float(py_value)
  elif not isinstance(py_value, str) and isinstance(py_value, abc.Iterable):
    return [py_value_to_js_dict(value) for value in list(py_value)]
  else:
    return py_value


# TODO(yaml) Consider adding optional language version parameter to support
#  ECMAScript 5 and 6
def _expand_javascript_mapping_func(
    original_fields, expression=None, callable=None, path=None, name=None):

  if quickjs is None:
    raise ValueError(
        "Javascript mapping functions are not supported because the "
        "quickjs-ng library is not installed.")

  if expression:
    source_code = f"""
    function udf(__row__) {{
      with (__row__) {{
        return ({expression});
      }}
    }}
    """
    user_entrypoint = 'udf'

  elif callable:
    source_code = f"var __udf__ = ({callable});"
    user_entrypoint = '__udf__'

  else:

View on GitHub (pinned to 12126d8942)