Fix 'Cannot find module @mariozechner/clipboard-linux-arm-gnueabihf' in OpenClaw
Fix OpenClaw crash on Linux ARM due to missing clipboard module.
TL;DR: The Instant Fix
The Problem: OpenClaw crashes on Linux ARM (Raspberry Pi, etc.) because the clipboard package doesn't have a prebuilt native binary for ARM architecture.
The Error:
Error: Cannot find module '@mariozechner/clipboard-linux-arm-gnueabihf'The Solution:
- Quick Fix: Upgrade OpenClaw to latest version (dependency is now optional)
- Workaround: Use Docker (bypass native dependencies)
Deploy on Vultr (H100/A100 Ready) (High Availability & Limited Time Promotion for new accounts)
The Log: What You're Seeing
The Error:
[INFO] Starting OpenClaw...
[ERROR] Error: Cannot find module '@mariozechner/clipboard-linux-arm-gnueabihf'
Require stack:
- /app/dist/index.js:15:23
- at processTicksAndRejections (node:internal/process/task_queues:96:5)
[System] Clipboard module failed to load
[Agent] Unable to use clipboard functionality
Context: This error occurs on Linux ARM devices (Raspberry Pi, ARM servers, etc.) when OpenClaw tries to load the clipboard package. The package has prebuilt binaries for x86/x64 but not for ARM.
Observed Behavior: OpenClaw starts but crashes or loses clipboard functionality. Copy/paste operations may fail silently.
Why This Happens (It's an Architecture Mismatch)
This is a Prebuilt Binary Availability Issue.
OpenClaw uses the @mariozechner/clipboard package for clipboard operations. This package includes:
- Prebuilt native binaries for x86/x64 (Intel/AMD)
- Fallback pure-JS implementation for other architectures
On Linux ARM (aarch64), if the npm version is old (< 9.0.0), it may:
- Try to load a non-existent ARM binary
- Fail to fall back to the pure-JS implementation
- Crash with "Cannot find module" error
The ARM Architecture Problem
| Architecture | Prebuilt Binary | Pure-JS Fallback | Status |
|---|---|---|---|
| x86/x64 (Intel/AMD) | ā Included | ā Available | Works out of box |
| ARM64 (Raspberry Pi, ARM servers) | ā Not included | ā ļø May not load | Needs npm v9+ |
| ARMv7 (Raspberry Pi Zero/older) | ā Not included | ā Not compatible | Needs manual build |
Solution A: Upgrade OpenClaw (Recommended)
The clipboard dependency was made optional in newer versions of OpenClaw. Upgrading is the cleanest fix.
Step 1: Check Current Version
# Check current OpenClaw version
openclaw --version
# Or if installed via npm
npm list -g openclaw
Step 2: Upgrade OpenClaw
# Uninstall old version
npm uninstall -g openclaw
# Install latest version
npm install -g openclaw@latest
# Or using npx (always runs latest)
npx openclaw@latest start
Step 3: Verify Installation
# Check version again
openclaw --version
# Start OpenClaw
openclaw start
# Should work without clipboard errors
Why This Works: Newer versions of OpenClaw made the clipboard dependency optional. If it can't load, OpenClaw continues without clipboard functionality instead of crashing.
Solution B: Use Docker (Bypass Native Dependencies)
If upgrading doesn't work or you need immediate results, Docker bypasses all native module issues.
Step 1: Create Dockerfile
FROM node:18-alpine
# Install OpenClaw
RUN npm install -g openclaw
# Set working directory
WORKDIR /app
# Everything works in Linux container
CMD ["openclaw"]
Step 2: Build and Run
# Build image
docker build -t openclaw-arm .
# Run container
docker run -it --rm openclaw-arm
Why This Works: Docker creates an isolated environment where OpenClaw runs without ARM-specific native dependencies.
The "Survival" Recommendation
Stop debugging ARM compatibility issues.
Every hour you spend rebuilding modules, searching for ARM-compatible packages, or debugging architecture mismatches is an hour you're not shipping.
Debugging ARM compatibility is a huge time sink. x86 VPS just works.
Local ARM vs Cloud VPS Comparison
| Issue | Local ARM (Raspberry Pi, etc.) | Cloud VPS (x86) |
|---|---|---|
| Prebuilt binaries | Often missing | Always included |
| Clipboard module | May need manual build | Works immediately |
| Debug time | 2-4 hours (build, test, fail) | 0 minutes |
| Performance | Limited CPU/RAM | Scalable |
| Cost | Hardware upfront + time | Hourly billing options |
Deploy on Vultr (H100/A100 Ready) (High Availability & Limited Time Promotion for new accounts)
Complete Working Example
Verified Linux ARM Configuration
# 1. Check architecture
uname -m
# Output: aarch64 (ARM64)
# 2. Check current OpenClaw version
openclaw --version
# Or: npm list -g openclaw
# 3. Uninstall old version
npm uninstall -g openclaw
# 4. Install latest version
npm install -g openclaw@latest
# 5. Verify it works
openclaw start
# Should start without clipboard errors
Docker Alternative (Instant Fix)
FROM node:18-alpine
# Install OpenClaw
RUN npm install -g openclaw
# Set working directory
WORKDIR /app
CMD ["openclaw"]
# Build and run
docker build -t openclaw-arm .
docker run -it --rm openclaw-arm
FAQ
Q: Why does this happen on Raspberry Pi but not x86?
A: The clipboard package only includes prebuilt binaries for x86/x86_64. On ARM (aarch64), the package tries to load an ARM binary that doesn't exist. Newer OpenClaw versions made this dependency optional to fix this issue.
Q: Will upgrading OpenClaw break my configuration?
A: Usually not. OpenClaw maintains backward compatibility for config files. Your openclaw.json should work with newer versions. Backup your config before upgrading just in case.
Q: Can I just use x86 VPS instead of ARM?
A: Yes, and it's usually faster. x86 servers have better performance and more software compatibility. ARM is great for power efficiency, but for development work, x86 VPS saves debugging time.
Q: What if I can't upgrade OpenClaw?
A: Use Docker. It creates an isolated Linux environment that bypasses ARM native module issues entirely. See Solution B above for Docker setup.
Q: Is this specific to OpenClaw?
A: No. Any app using @mariozechner/clipboard on Linux ARM will have this issue. OpenClaw fixed it by making the dependency optional. Other apps may still have this problem.
Related Fixes
-
Fix Docker EACCES: Permission Denied - Docker permission issues
-
Fix 'spawn npm ENOENT' on Windows - Node installation issues
-
Fix 'spawn EINVAL' on Windows - Permissions
-
Running OpenClaw with DeepSeek R1: Complete Guide - Setup and configuration
Bottom Line: ARM compatibility issues are time sinks.
Upgrade OpenClaw to the latest version for the quick fix, or use x86 VPS to avoid ARM debugging entirely.
Deploy on Vultr (H100/A100 Ready) (High Availability & Limited Time Promotion for new accounts)
Still Stuck? Check Your Hardware
Sometimes the code is fine, but the GPU is simply refusing to cooperate. Before you waste another hour debugging, compare your specs against the Hardware Reality Table to see if you are fighting impossible physics.
Bookmark this site
New fixes are added as soon as they appear on GitHub Issues.
Browse Error Index ā