OpenHuman Installation Failed? 2026 Complete Error Fix Guide (Mac / Windows / Docker / Node.js)

OpenHuman shot to prominence in early 2026 with its “local-first, long-term memory” personal AI Agent pitch — but the project is still in Early Beta. Its Rust + TypeScript dual-stack build process, system-level dependencies, and platform permission models differ enough that a lot of people get stuck on the very first step. This guide systematically covers the most common error scenarios across four platforms, with copy-paste fix commands for each one, so you can be up and running in under 30 minutes.

Quick Reference

• Mac (Apple Silicon / Intel): Gatekeeper block, missing Rust toolchain, Xcode CLT version conflict
• Windows: Path spaces and non-ASCII characters, WSL2 kernel too old, MSVC vs GNU toolchain mix
• Docker: Image pull timeout, arm64/amd64 architecture mismatch, volume permission errors
• Node.js: Version mismatch, native module rebuild failure, pnpm/npm dependency conflicts

1. Mac Troubleshooting (Apple Silicon & Intel)

1.1 Error: “openhuman” cannot be opened because the developer cannot be verified

This is macOS Gatekeeper blocking a binary that has not been notarized by Apple. It's especially common on Apple Silicon Macs, because not every OpenHuman release goes through Apple's notarization workflow.

Fix A (recommended — allow just this file):

# Remove quarantine attribute in Terminal once; then double-click opens normally
xattr -dr com.apple.quarantine /Applications/OpenHuman.app

Fix B (System Settings): Open System Settings → Privacy & Security, scroll to the bottom, find the blocked app, and click “Open Anyway”.

1.2 Error: error: linker `cc` not found

The Rust compiler can't find a C linker — usually because Xcode Command Line Tools are not installed or are out of date.

# Install Xcode CLT (~2 GB, requires network on first install)
xcode-select --install

# If already installed but still erroring, reset the path
sudo xcode-select --reset

# Verify the version
xcode-select -p
# Output should be /Library/Developer/CommandLineTools or /Applications/Xcode.app/...

1.3 Error: rustup: command not found or Rust version too old

OpenHuman's Rust core typically requires stable ≥ 1.78 (check rust-toolchain.toml for the exact pin).

# Install rustup (skip if already installed)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Reload shell environment
source "$HOME/.cargo/env"

# Update to latest stable
rustup update stable

# Switch to the version required by the repo (rust-toolchain.toml applied automatically)
rustup show

1.4 Error: architecture arm64 is not compatible on Apple Silicon

Some npm native addons or system libraries don't ship an arm64 build, or you have both an arm64-native and a Rosetta Homebrew installed simultaneously.

# Confirm current shell architecture
uname -m  # should output arm64 (native M-series shell)

# Confirm Homebrew path (native arm64 should be at /opt/homebrew)
which brew

# If brew points to /usr/local (Rosetta), switch to arm64 shell first
arch -arm64 /bin/zsh
arch -arm64 brew install openssl pkg-config

1.5 Error: error: failed to run custom build command for `ring`

The ring crate needs Clang/LLVM and, on Mac, an explicit OpenSSL path.

# Install OpenSSL 3 via Homebrew
brew install openssl@3

# Set build environment variables temporarily (or add to ~/.zshrc)
export OPENSSL_DIR="$(brew --prefix openssl@3)"
export OPENSSL_NO_VENDOR=1

# Build again
cargo build --release

2. Windows Troubleshooting

2.1 Error: Build fails because the path contains spaces or non-ASCII characters

Cargo and many npm native modules have poor tolerance for spaces or non-ASCII characters in paths.

:: Clone repo to a pure ASCII path with no spaces, e.g.
git clone https://github.com/tinyhumansai/openhuman C:\dev\openhuman

:: Also migrate Cargo cache to a safe path (run in PowerShell)
[System.Environment]::SetEnvironmentVariable("CARGO_HOME","C:\dev\.cargo","User")
[System.Environment]::SetEnvironmentVariable("RUSTUP_HOME","C:\dev\.rustup","User")

2.2 Error: LINK : fatal error LNK1181: cannot open input file

The MSVC toolchain is missing or not properly configured. OpenHuman on Windows recommends MSVC rather than GNU.

:: 1. Install Visual Studio 2022 Build Tools (or full VS 2022)
::    Required component: "Desktop development with C++" → MSVC v143 + Windows SDK

:: 2. Switch Rust to MSVC target
rustup default stable-x86_64-pc-windows-msvc
rustup target add x86_64-pc-windows-msvc

:: 3. Confirm linker can be found
where link
:: Example output: C:\Program Files (x86)\Microsoft Visual Studio\...\link.exe

2.3 Error: WSL2 kernel version too old

If you're running OpenHuman inside WSL2, the kernel must be ≥ 5.15.

:: Update WSL kernel in PowerShell (Administrator)
wsl --update

:: Verify version
wsl --version

:: Set the target distro to WSL2 mode
wsl --set-version Ubuntu-22.04 2

2.4 Error: 'python' is not recognized

Some npm native module build scripts rely on a python command.

:: Option A: Install python-is-python3 (WSL2 Ubuntu)
sudo apt install python-is-python3

:: Option B: Windows native – point npm to python3 globally
npm config set python python3

:: Option C: Install windows-build-tools (deprecated, prefer VS Build Tools)
:: No longer recommended, for reference only

2.5 Error: error MSB8036: The Windows SDK version X was not found

:: Open Visual Studio Installer → Modify → Individual components
:: Check the corresponding Windows SDK (10.0.22621 or newer recommended) and install
:: Restart terminal after installation before building

3. Docker Troubleshooting

3.1 Error: pull access denied or pull timeout

GitHub Container Registry and Docker Hub are rate-limited or blocked in some regions.

# Option A: Configure a registry mirror (edit in Docker Desktop → Settings → Docker Engine)
# Add the following JSON field:
# "registry-mirrors": ["https://mirror.gcr.io","https://docker.mirrors.ustc.edu.cn"]

# Option B: Export the image on a machine with network access, then import on the target
docker save ghcr.io/tinyhumansai/openhuman:latest | gzip > openhuman.tar.gz
# Import on the target machine
gunzip -c openhuman.tar.gz | docker load

3.2 Error: image platform (linux/amd64) does not match expected platform (linux/arm64)

Pulling the official amd64 image on an Apple Silicon Mac triggers this warning (plus Rosetta emulation overhead).

# Pull with explicit platform flag (triggers Rosetta emulation, some performance cost)
docker pull --platform linux/amd64 ghcr.io/tinyhumansai/openhuman:latest

# If an official arm64 image is available, prefer the native image
docker pull --platform linux/arm64 ghcr.io/tinyhumansai/openhuman:latest

# Specify platform at runtime
docker run --platform linux/arm64 ghcr.io/tinyhumansai/openhuman:latest

3.3 Error: permission denied — container cannot write to mounted volume

The container process runs as a non-root user, but the host directory is owned by root or a different uid.

# Option A: Grant host directory permissions to the container user (uid usually 1000)
sudo chown -R 1000:1000 ./openhuman-data

# Option B: Run as root in docker run (dev only, not recommended for production)
docker run --user root ...

# Option C: Specify user in Docker Compose
# services:
#   openhuman:
#     user: "1000:1000"
#     volumes:
#       - ./openhuman-data:/app/data

3.4 Error: exec: "sh": executable file not found

The image uses a distroless or scratch base — no shell is available.

# Enter the container using the full bash path (if it exists)
docker exec -it openhuman /bin/bash

# If the image truly has no shell, build a debug image and mount the original data volume
docker build -f Dockerfile.debug -t openhuman-debug .
docker run -it --volumes-from openhuman openhuman-debug /bin/bash

3.5 Docker Compose: dependency failed to start

OpenHuman's database or vector-index service starts slowly, causing the main service health check to time out.

# Add a healthcheck for dependent services in compose.yml
# services:
#   db:
#     healthcheck:
#       test: ["CMD", "pg_isready", "-U", "openhuman"]
#       interval: 5s
#       retries: 10
#   openhuman:
#     depends_on:
#       db:
#         condition: service_healthy

# Manually inspect service logs to identify the root cause
docker compose logs --tail=50 db
docker compose logs --tail=50 openhuman

4. Node.js Troubleshooting

4.1 Error: The engine "node" is incompatible with this module

OpenHuman's frontend and plugin layer usually requires Node.js ≥ 20 LTS.

# Switch to the required version with nvm (LTS 20 or 22 recommended)
nvm install 20
nvm use 20
node --version  # confirm output is v20.x.x

# If using fnm (faster version manager)
fnm install 20
fnm use 20

4.2 Error: gyp ERR! build error — native module build failure

Dependencies like better-sqlite3 or sharp contain native C++ addons and need a full build toolchain.

# macOS: ensure Xcode CLT is installed
xcode-select --install

# Windows: install node-gyp globally in PowerShell (Administrator)
npm install -g node-gyp
# Also ensure Visual Studio Build Tools are installed (see section 2.2)

# Linux (Ubuntu/Debian)
sudo apt-get install -y python3 make g++

# Force rebuild all native modules
npm rebuild
# Or using pnpm
pnpm rebuild

4.3 Error: Cannot find module '...' ERR_MODULE_NOT_FOUND

Incomplete dependency install, or node_modules cache is out of sync with the lockfile.

# Full clean reinstall
rm -rf node_modules
rm package-lock.json   # or pnpm-lock.yaml / yarn.lock

# Reinstall using the project's package manager (pnpm example)
corepack enable
pnpm install --frozen-lockfile

4.4 Error: ENOSPC: System limit for number of file watchers reached

Linux's default inotify watcher limit is too low for hot-reload dev mode.

# Increase temporarily (resets after reboot)
sudo sysctl fs.inotify.max_user_watches=524288

# Persist the setting
echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

4.5 Error: Error: EACCES: permission denied, mkdir '.../.npm'

npm's global directory has permission issues.

# Change npm global directory to a user-writable path
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH
# Add the export above to ~/.zshrc or ~/.bashrc to persist

5. General Troubleshooting Checklist

Whatever platform you're on, work through this checklist in order before diving deeper:

6. Still Stuck? What to Try Next

• Search the issue tracker: Look up key words from the error in GitHub Issues.
• File a detailed issue: Paste the output of cargo build 2>&1 | head -100 along with rustup show, node --version, and your OS version.
• Fall back to Docker: If the native install keeps failing, a Docker container is the fastest way around environment differences.
• Offload inference: If local compute is the issue, point OpenHuman's model endpoint at a remote Ollama instance running on a high-memory Apple Silicon Mac.

For the pattern of “can't install locally → run on a remote Mac node → gradually migrate back,” see our OpenHuman 20-minute knowledge base article.

7. Conclusion

Ninety percent of OpenHuman installation problems come down to three root causes: incomplete build toolchain (Rust/C++ compiler), runtime version mismatch (Node.js/Python), and platform permission or network restrictions (Gatekeeper/MSVC/image pull). Work through this guide section by section and you should resolve most issues within 30 minutes.

If you just want to try OpenHuman quickly without wrestling with environment setup, Docker is the fastest starting point. If you want maximum performance and full local control, invest the time in getting the Rust toolchain right and pick a machine with plenty of unified memory.