GLIBC_2.28 Not Found Error in Node.js

Problem Statement

When attempting to run Node.js on Linux systems, you may encounter the error:

node: /lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.28' not found (required by node)

This occurs because newer versions of Node.js (v18 and above) require GLIBC (GNU C Library) version 2.28 or higher, but your Linux distribution ships with an older version.

Common Affected Systems

• Ubuntu 18.04 LTS (Bionic Beaver) - ships with GLIBC 2.27
• Debian 10 (Buster) - ships with GLIBC 2.28
• Older Linux distributions

Understanding the GLIBC Requirement

GLIBC is a fundamental library that provides core system functions for Linux applications. Each Node.js release is compiled against a specific GLIBC version, and attempting to run it on a system with an older GLIBC version will fail.

Check GLIBC Version

ldd --version

Check Available GLIBCXX Symbols

# For libstdc++ compatibility issues
strings /usr/lib/x86_64-linux-gnu/libstdc++.so.6 | grep GLIBCXX

Solutions

1. Downgrade Node.js Version (Recommended)

The simplest solution is to install a Node.js version compatible with your system's GLIBC:

Using NVM

# Install Node.js v16 (compatible with GLIBC 2.27)
nvm install 16
nvm use 16

# Make it default
nvm alias default 16

Using n package

# System-wide installation
sudo npm install -g n
sudo n 16

Compatibility Table

Node.js Version	Minimum GLIBC Required	Ubuntu Version Support
Node.js 14.x	GLIBC 2.17	Ubuntu 14.04+
Node.js 16.x	GLIBC 2.17	Ubuntu 14.04+
Node.js 18.x	GLIBC 2.28	Ubuntu 20.04+
Node.js 20.x	GLIBC 2.28	Ubuntu 20.04+

2. Upgrade Your Linux Distribution

For long-term compatibility, upgrade to a newer Linux distribution:

# For Ubuntu systems
sudo do-release-upgrade

Supported distributions for Node.js 18+:

• Ubuntu 20.04 LTS (Focal Fossa) or later
• Debian 11 (Bullseye) or later

3. Use Unofficial Builds with Older GLIBC

For systems where upgrading isn't feasible, use unofficial Node.js builds compiled against older GLIBC versions:

# Download from unofficial builds repository
# Replace with your desired version and architecture
wget https://unofficial-builds.nodejs.org/download/release/v18.19.0/node-v18.19.0-linux-x64-glibc-2.17.tar.gz
tar -xzf node-v18.19.0-linux-x64-glibc-2.17.tar.gz
sudo mv node-v18.19.0-linux-x64 /opt/node
sudo ln -sf /opt/node/bin/node /usr/local/bin/node
sudo ln -sf /opt/node/bin/npm /usr/local/bin/npm

4. Docker-Based Solution (Advanced)

Run Node.js in a container without installing it system-wide:

# Replace with your Node.js version and command
docker run -it --rm -v $(pwd):/app -w /app node:18-alpine node your-script.js

# For development with package.json
docker run -it --rm -v $(pwd):/app -w /app node:18-alpine npm install

5. Manual GLIBC Upgrade (Not Recommended)

Advanced Warning

Compiling GLIBC manually can break system stability. Only attempt this if you understand the risks.

# Install build dependencies
sudo apt install -y gawk

# Download and compile GLIBC 2.28
wget -c https://ftp.gnu.org/gnu/glibc/glibc-2.28.tar.gz
tar -zxf glibc-2.28.tar.gz
cd glibc-2.28
mkdir build && cd build
../configure --prefix=/opt/glibc-2.28
make -j$(nproc)
sudo make install

# Patch Node.js to use the new GLIBC
sudo patchelf --set-interpreter /opt/glibc-2.28/lib/ld-linux-x86-64.so.2 \
              --set-rpath /opt/glibc-2.28/lib:/lib/x86_64-linux-gnu:/usr/lib/x86_64-linux-gnu \
              /path/to/node

Special Cases

GitHub Actions Runners

For self-hosted GitHub Actions runners on Ubuntu 18.04:

# Replace the Node.js binary in the runner directory
cp /usr/bin/node /path/to/actions-runner/externals/node20/bin/node

# Restart the service
sudo ./svc.sh uninstall
sudo ./svc.sh install
sudo ./svc.sh start

Visual Studio Code Remote SSH

For VSCode Remote SSH extension issues:

# Replace the problematic node binary with a symlink
cd ~/.vscode-server/bin/<UUID>
mv node node.broken
ln -s /usr/bin/node .

Prevention and Best Practices

1. Check compatibility before installing new Node.js versions
2. Use NVM for managing multiple Node.js versions
3. Regularly update your operating system
4. Test in containers when targeting multiple environments
5. Consider Docker for development and production environments

Conclusion

The "GLIBC_2.28 not found" error occurs due to a mismatch between Node.js version requirements and system library versions. For most users, downgrading to Node.js v16 provides the simplest solution. For long-term projects, consider upgrading your operating system or using containerization to ensure compatibility across different environments.