nodejs/node · error · RuntimeError

Environment variable ZOSLIB_INCLUDES is not set

Error message

Environment variable ZOSLIB_INCLUDES is not set

What it means

On IBM z/OS (sys.platform == 'zos'), installing node headers requires copying the zoslib headers into include/node/zoslib. install.py reads the ZOSLIB_INCLUDES environment variable to find them and aborts if it is unset.

Source

Thrown at tools/install.py:374

  if 'false' == options.variables.get('node_shared_libuv'):
    subdir_files(options, 'deps/uv/include', 'include/node/', action)

  if 'true' == options.variables.get('node_use_openssl') and \
     'false' == options.variables.get('node_shared_openssl'):
    subdir_files(options, 'deps/openssl/openssl/include/openssl', 'include/node/openssl/', action)
    subdir_files(options, 'deps/openssl/config/archs', 'include/node/openssl/archs', action)
    subdir_files(options, 'deps/openssl/config', 'include/node/openssl', action)

  if 'false' == options.variables.get('node_shared_zlib'):
    action(options, [
      'deps/zlib/zconf.h',
      'deps/zlib/zlib.h',
    ], 'include/node/')

  if sys.platform == 'zos':
    zoslibinc = os.environ.get('ZOSLIB_INCLUDES')
    if not zoslibinc:
      raise RuntimeError('Environment variable ZOSLIB_INCLUDES is not set\n')
    if not os.path.isfile(zoslibinc + '/zos-base.h'):
      raise RuntimeError('ZOSLIB_INCLUDES is not set to a valid location\n')
    subdir_files(options, zoslibinc, 'include/node/zoslib/', wanted_zoslib_headers)

def run(options):
  if options.headers_only:
    if options.command == 'install':
      headers(options, install)
      return
    if options.command == 'uninstall':
      headers(options, uninstall)
      return
  else:
    if options.command == 'install':
      files(options, install)
      return
    if options.command == 'uninstall':
      files(options, uninstall)

View on GitHub (pinned to 1b2de5e052)

Solutions

Export ZOSLIB_INCLUDES to your zoslib include directory before installing, e.g. `export ZOSLIB_INCLUDES=/path/to/zoslib/include` (the dir must contain zos-base.h).
Source the z/OS build environment setup script that defines it.
Set it persistently in your shell profile / CI environment.

Example fix

// before
python tools/install.py install   # on z/OS, ZOSLIB_INCLUDES unset
// after
export ZOSLIB_INCLUDES=/usr/local/zoslib/include
python tools/install.py install

Defensive patterns

Strategy: validation

Validate before calling

import os, sys, pathlib
if sys.platform=='zos':
    v=os.environ.get('ZOSLIB_INCLUDES')
    assert v, 'ZOSLIB_INCLUDES must be set on z/OS'
    assert pathlib.Path(v,'zos-base.h').is_file()

Prevention

On z/OS, always source the env setup that exports ZOSLIB_INCLUDES before building/installing node.
Add the variable to CI environment definitions for z/OS jobs.

When it happens

Trigger: Running `python tools/install.py install` (or the header install path) on z/OS without ZOSLIB_INCLUDES exported in the environment.

Common situations: Fresh z/OS build machine whose env-setup script was not sourced; CI job missing the variable; switching to a new shell that lost the export.

Related errors

AI-assisted analysis of nodejs/node@1b2de5e052 (2026-08-13). Data as JSON: /api/errors/2418a0f090ef0744. Report an issue: GitHub.