Troubleshooting

One page for install and setup problems, quick diagnostics, common issues, and step-by-step fixes for pair-cli.

Install or setup problem? This page collects every known issue and its fix, from permission errors to corrupted installs.

Quick Diagnostics

Before diving into specific issues, run these commands to gather diagnostic information:

# Check your environment
node --version        # Should be 18 or higher
pnpm --version       # Should be installed
pair-cli --version   # Current pair-cli version (if installed)
 
# Check installation location
which pair-cli       # Should show installation path
npm list -g @foomakers/pair-cli  # Global npm installation check

Quick Fixes

Issue	Quick Fix
Permission denied	Use nvm, or fix the npm prefix
Command not found	Check PATH, or use `npx pair-cli`
Node version	`nvm use 18`
Network blocked	Use manual install
Files not created	Check directory permissions

Recommended fix: use a Node version manager (nvm). It installs Node in your home directory, so global installs never need elevated permissions (and it fixes Node-version problems at the same time):

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc
nvm install 18
nvm use 18
npm install -g @foomakers/pair-cli

Alternatives if you can't use nvm:

# Option 2: Point npm's global prefix at a user-writable directory
npm config set prefix ~/.npm-global
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.profile
source ~/.profile
npm install -g @foomakers/pair-cli
 
# Option 3: Use pnpm (avoids permission issues)
npm install -g pnpm
pnpm add -g @foomakers/pair-cli
 
# Option 4: Install locally in the project
pnpm add -D @foomakers/pair-cli
# Use with: pnpm dlx pair-cli

Avoid sudo npm install -g: it hides the underlying problem and creates root-owned files that break later installs.

On Windows:

# Run PowerShell as Administrator, then:
npm install -g @foomakers/pair-cli

Problem: Can't write to `/usr/local/lib/node_modules`

Same root cause: npm's global prefix points at a system directory. Use nvm (recommended, above) or move the prefix:

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.profile
source ~/.profile
 
npm install -g @foomakers/pair-cli

Node Version Issues

Problem: `Unsupported Node.js version` or compatibility errors

Check your Node version:

node --version
# Must be 18.0.0 or higher

Fix with Node Version Manager (recommended):

# Install nvm (if not already installed)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc
 
# Install and use Node 18+
nvm install 18
nvm use 18
nvm alias default 18
 
# Verify
node --version
npm install -g @foomakers/pair-cli

Fix with Volta (alternative):

# Install volta
curl https://get.volta.sh | bash
source ~/.bashrc
 
# Install Node 18
volta install node@18
volta install npm
 
# Verify and install
node --version
npm install -g @foomakers/pair-cli

Problem: Multiple Node versions causing conflicts

# Clean up and start fresh
npm uninstall -g @foomakers/pair-cli
nvm use 18  # or your preferred version
npm cache clean --force
npm install -g @foomakers/pair-cli

pnpm Issues

Problem: `pnpm` command not found

Install pnpm:

# Via npm
npm install -g pnpm
 
# Via Homebrew (macOS)
brew install pnpm
 
# Via curl (Unix)
curl -fsSL https://get.pnpm.io/install.sh | sh

Problem: pnpm store corruption or cache issues

Clean and reinstall:

# Clear pnpm store and cache
pnpm store prune
pnpm cache clear
 
# Remove existing installation
pnpm remove -g @foomakers/pair-cli
 
# Reinstall fresh
pnpm add -g @foomakers/pair-cli

Problem: `ERR_PNPM_STORE_BROKEN` or store corruption

Reset pnpm completely:

# Remove the store
rm -rf ~/.pnpm-store
rm -rf ~/.pnpm-state
 
# Reinstall pnpm and pair-cli
npm install -g pnpm
pnpm add -g @foomakers/pair-cli

Command Not Found & PATH Issues

Problem: `pair-cli` command not found after installation

Verify installation location:

# Check if installed
npm list -g @foomakers/pair-cli
pnpm list -g @foomakers/pair-cli
 
# Check PATH
echo $PATH
which pair-cli

Fix PATH issues:

# Add npm global bin to PATH
npm config get prefix  # Note the output path
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.profile
source ~/.profile
 
# If using nvm, ensure the right Node version is active
nvm current
nvm use 18
 
# Restart terminal or source profile
source ~/.bashrc  # or ~/.zshrc
 
# For local installs, use npx
npx pair-cli --version

Problem: Command exists but fails to run

Clean reinstall steps:

# 1. Remove completely
npm uninstall -g @foomakers/pair-cli
# or
pnpm remove -g @foomakers/pair-cli
 
# 2. Clear caches
npm cache clean --force
# or
pnpm store prune
 
# 3. Clear global node_modules (careful!)
rm -rf ~/.npm/_global/node_modules/@pair
# or similar path for your system
 
# 4. Reinstall fresh
npm install -g @foomakers/pair-cli

Problem: Version conflicts or "command not found" after update

Deterministic cleanup:

# 1. Find all pair-cli installations
find /usr/local -name "*pair-cli*" 2>/dev/null
find ~/.npm -name "*pair-cli*" 2>/dev/null
find ~/.pnpm -name "*pair-cli*" 2>/dev/null
 
# 2. Remove all found instances
# (Review the list first, then remove manually)
 
# 3. Clean install
npm install -g @foomakers/pair-cli
 
# 4. Verify
pair-cli --version
which pair-cli

Native Build Failures

Problem: `node-gyp` errors or native module build failures

On macOS:

# Install Xcode Command Line Tools
xcode-select --install
 
# Clear and reinstall
npm uninstall -g @foomakers/pair-cli
npm install -g @foomakers/pair-cli

On Linux (Ubuntu/Debian):

# Install build tools
sudo apt update
sudo apt install build-essential python3-dev python3-distutils
 
# Clear and reinstall
npm uninstall -g @foomakers/pair-cli
npm install -g @foomakers/pair-cli

On Linux (CentOS/RHEL/Fedora):

# Install development tools
sudo yum groupinstall "Development Tools"
# or for newer versions:
sudo dnf groupinstall "Development Tools"
 
# Clear and reinstall
npm uninstall -g @foomakers/pair-cli
npm install -g @foomakers/pair-cli

On Windows:

# Install Windows Build Tools
npm install -g windows-build-tools

Offline/Network-Restricted Installs

Problem: No internet access or corporate firewall blocks npm

Use manual artifacts:

Download from GitHub Releases:
- pair-cli-manual-vX.Y.Z.zip for manual installation
Extract and use:

# Extract the ZIP file
unzip pair-cli-manual-vX.Y.Z.zip
cd pair-cli-manual-vX.Y.Z
 
# Run directly (no installation needed)
./bin/pair-cli --version
./bin/pair-cli --help
 
# Optional: Add to PATH
echo 'export PATH=$HOME/pair-cli-manual-vX.Y.Z/bin:$PATH' >> ~/.profile
source ~/.profile

On Windows, run pair-cli.cmd from the extracted archive instead of pair-cli (use Git Bash or WSL if you hit line-ending or path issues).

Problem: Corporate proxy blocking installs

# Configure npm for corporate proxy
npm config set proxy http://proxy.company.com:8080
npm config set https-proxy http://proxy.company.com:8080
npm config set registry https://registry.npmjs.org/
 
# If authentication required:
npm config set proxy http://username:password@proxy.company.com:8080
 
# Install through proxy
npm install -g @foomakers/pair-cli

Runtime Issues

Problem: `pair-cli install` fails with "permission denied"

Solution: Ensure write access to the target directory.

# Check permissions
ls -la .
 
# Fix permissions if needed
chmod 755 .
 
# Or run in a directory you own
mkdir ~/my-project
cd ~/my-project
pair-cli install

Problem: `pair-cli install` runs but no files are created

Solutions:

# Check current directory
pwd
 
# Ensure you have write permissions
touch test.txt && rm test.txt
 
# Try with debug-level logging (if available)
pair-cli install --log-level debug
 
# Check if assets are available
pair-cli install --list-targets

Problem: Installed assets seem outdated

Solution: Update to the latest version.

# Update all assets
pair-cli update
 
# Or reinstall
pair-cli install --force  # if available

Getting Additional Help

If these solutions don't resolve your issue:

Check existing issues: GitHub Issues
Ask the community: GitHub Discussions
Open a new issue: Include output from these diagnostic commands:

# System information
uname -a                    # OS and architecture
node --version             # Node.js version
npm --version              # npm version
pnpm --version             # pnpm version (if installed)
 
# pair-cli specific
pair-cli --version         # pair-cli version
which pair-cli             # Installation location
npm list -g @foomakers/pair-cli # Installation details
 
# Environment
echo $PATH                 # PATH variable
npm config get prefix     # npm global prefix
npm config list           # npm configuration

Include in your report: operating system and version, Node.js and npm/pnpm versions, the complete error message, and the steps you've already tried.

Do not include: personal paths with usernames, API keys or tokens, corporate proxy credentials.

Prevention

Always use Node 18+ (managed with nvm) and pnpm
Install globally with nvm-managed Node, or locally with pnpm dlx
Test in a clean directory first
Keep pair-cli updated: npm update -g @foomakers/pair-cli

FAQ: questions about the process, languages, tools and customization
Quickstart: the install steps these fixes refer to
Verify your setup: the checklist to run after a fix