Version: 2.1.0 Last Updated: 2025-01-24
- Quick Diagnosis
- Installation Issues
- Network & Connectivity Issues
- Permission & Access Issues
- OS-Specific Issues
- IDE Configuration Issues
- Agent Activation Issues
- Diagnostic Commands
- Getting Help
Run this diagnostic command first to identify common issues:
npx aiox-core statusIf the status command fails, work through the sections below based on your error message.
Symptoms:
'npx' is not recognized as an internal or external command
Cause: Node.js or npm is not installed or not in PATH.
Solution:
# Check if Node.js is installed
node --version
# If not installed:
# Windows: Download from https://nodejs.org/
# macOS: brew install node
# Linux: nvm install 18
# Verify npm is available
npm --version
# If npm is missing, reinstall Node.jsSymptoms:
⚠️ Inappropriate Installation Directory Detected
Current directory: /Users/username
Synkra AIOX should be installed in your project directory,
not in your home directory or temporary locations.
Cause: Running the installer from home directory, /tmp, or npx cache.
Solution:
# Navigate to your project directory first
cd /path/to/your/project
# Then run the installer
npx aiox-core installSymptoms:
Installation failed: ENOENT: no such file or directory
Cause: Target directory doesn't exist or has incorrect permissions.
Solution:
# Create the directory first
mkdir -p /path/to/your/project
# Navigate to it
cd /path/to/your/project
# Run installer
npx aiox-core installSymptoms:
Error: Synkra AIOX requires Node.js 18.0.0 or higher
Current version: 14.17.0
Cause: Node.js version is below minimum requirement.
Solution:
# Check current version
node --version
# Update using nvm (recommended)
nvm install 18
nvm use 18
# Or download latest LTS from nodejs.orgSymptoms:
npm ERR! code E404
npm ERR! 404 Not Found - GET https://registry.npmjs.org/aiox-core
Cause: Package not found on npm registry (network issue or typo).
Solution:
# Clear npm cache
npm cache clean --force
# Verify registry
npm config get registry
# Should be: https://registry.npmjs.org/
# If using custom registry, reset to default
npm config set registry https://registry.npmjs.org/
# Retry installation
npx aiox-core installSymptoms:
npm ERR! EACCES: permission denied, mkdir '/usr/local/lib/node_modules'
Cause: Global npm directory has incorrect permissions.
Solution:
# Option 1: Fix npm permissions (Linux/macOS)
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH
# Add the export line to ~/.bashrc or ~/.zshrc
# Option 2: Use npx instead of global install (recommended)
npx aiox-core install
# Option 3: Use nvm to manage Node.js
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 18Symptoms:
npm ERR! code ETIMEDOUT
npm ERR! errno ETIMEDOUT
npm ERR! network request to https://registry.npmjs.org/aiox-core failed
Cause: Network connectivity issue, firewall, or proxy blocking npm.
Solution:
# Check if npm registry is reachable
curl -I https://registry.npmjs.org/
# If behind a proxy, configure npm
npm config set proxy http://proxy.company.com:8080
npm config set https-proxy http://proxy.company.com:8080
# If using corporate SSL inspection, disable strict SSL (use with caution)
npm config set strict-ssl false
# Retry with verbose logging
npm install aiox-core --verboseSymptoms:
npm ERR! code UNABLE_TO_GET_ISSUER_CERT_LOCALLY
npm ERR! unable to get local issuer certificate
Cause: SSL certificate verification failing (common in corporate environments).
Solution:
# Add your company's CA certificate
npm config set cafile /path/to/your/certificate.pem
# Or disable strict SSL (use only if you trust your network)
npm config set strict-ssl false
# Verify and retry
npm config get strict-ssl
npx aiox-core installSymptoms:
npm ERR! network socket hang up
npm ERR! network This is a problem related to network connectivity.
Cause: Unstable internet connection or DNS issues.
Solution:
# Try using different DNS
# Windows: Control Panel > Network > DNS = 8.8.8.8, 8.8.4.4
# Linux: echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf
# Clear DNS cache
# Windows: ipconfig /flushdns
# macOS: sudo dscacheutil -flushcache
# Linux: sudo systemd-resolve --flush-caches
# Retry with a longer timeout
npm config set fetch-timeout 60000
npx aiox-core installSymptoms:
Error: EPERM: operation not permitted, unlink '/path/to/file'
Cause: File is locked by another process or insufficient permissions.
Solution:
# Windows: Close all IDE instances, then:
taskkill /f /im node.exe
# macOS/Linux: Check for locked processes
lsof +D /path/to/project
# Kill any process holding files
kill -9 <PID>
# Try installation again
npx aiox-core installSymptoms:
Error: EROFS: read-only file system
Cause: Trying to install on a read-only mount or system directory.
Solution:
# Verify filesystem is writable
touch /path/to/project/test.txt
# If this fails, the directory is read-only
# Check mount options
mount | grep /path/to/project
# Install to a writable directory instead
cd ~/projects/my-project
npx aiox-core installSymptoms:
Error: ENOTEMPTY: directory not empty, rmdir '.aiox-core'
Cause: Existing installation with modified files.
Solution:
# Backup existing installation
mv .aiox-core .aiox-core.backup
# Run installer with force flag
npx aiox-core install --force-upgrade
# If needed, restore custom files from backup
cp .aiox-core.backup/custom-files/* .aiox-core/Symptoms:
File cannot be loaded because running scripts is disabled on this system.
Solution:
# Check current policy
Get-ExecutionPolicy
# Set to RemoteSigned (recommended)
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
# Or use CMD instead of PowerShell
cmd
npx aiox-core installSymptoms:
Error: ENAMETOOLONG: name too long
Solution:
# Enable long paths in Windows 10/11
# Run as Administrator:
reg add "HKLM\SYSTEM\CurrentControlSet\Control\FileSystem" /v LongPathsEnabled /t REG_DWORD /d 1 /f
# Or use a shorter project path
cd C:\dev\proj
npx aiox-core installSymptoms:
bash: npm: command not found
Solution:
# Add Node.js to Git Bash path
# In ~/.bashrc or ~/.bash_profile:
export PATH="$PATH:/c/Program Files/nodejs"
# Or use Windows Terminal/CMD/PowerShell insteadSymptoms:
xcode-select: error: command line tools are not installed
Solution:
# Install Xcode Command Line Tools
xcode-select --install
# Follow the installation dialog
# Then retry
npx aiox-core installSymptoms:
Error: Unsupported architecture: arm64
Solution:
# Most packages work natively, but if issues persist:
# Install Rosetta 2 for x86 compatibility
softwareupdate --install-rosetta
# Use x86 version of Node.js (if needed)
arch -x86_64 /bin/bash
nvm install 18
npx aiox-core installSymptoms:
Error: Cannot find module '../build/Release/sharp-linux-x64.node'
Solution:
# Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y build-essential libvips-dev
# Fedora/RHEL
sudo dnf install vips-devel
# Clear npm cache and reinstall
npm cache clean --force
npx aiox-core installSymptoms:
Error: /lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.28' not found
Solution:
# Check GLIBC version
ldd --version
# If version is too old, use Node.js LTS for your distro:
# Ubuntu 18.04: Use Node.js 16 (max supported)
nvm install 16
nvm use 16
# Or upgrade your Linux distributionSymptoms: Agent commands (/dev, @dev) don't work after installation.
Solution:
-
Restart your IDE completely (not just reload)
-
Verify files were created:
# Claude Code ls .claude/commands/AIOX/agents/ # Cursor ls .cursor/rules/
-
Check IDE settings allow custom commands
-
Re-run installation for specific IDE:
npx aiox-core install --ide claude-code
Symptoms: IDE displays the agent file content instead of activating.
Solution:
- Check IDE version is compatible
- For Cursor: Ensure files have
.mdcextension - For Claude Code: Files should be in
.claude/commands/ - Restart IDE after installation
Symptoms:
Error: Agent 'dev' not found in .aiox-core/agents/
Solution:
# Verify agent files exist
ls .aiox-core/agents/
# If missing, reinstall core
npx aiox-core install --full
# Check core-config.yaml is valid
cat .aiox-core/core-config.yamlSymptoms:
YAMLException: bad indentation of a mapping entry
Solution:
# Validate YAML syntax
npx yaml-lint .aiox-core/agents/dev.md
# Common fixes:
# - Use spaces, not tabs
# - Ensure consistent indentation (2 spaces)
# - Check for special characters in strings (use quotes)
# Reinstall to get clean agent files
mv .aiox-core/agents/dev.md .aiox-core/agents/dev.md.backup
npx aiox-core install --full# Check AIOX installation status
npx aiox-core status
# List available Squads
npx aiox-core install
# Update existing installation
npx aiox-core update
# Show verbose logging
npx aiox-core install --verbose# Node.js and npm versions
node --version && npm --version
# npm configuration
npm config list
# Environment variables
printenv | grep -i npm
printenv | grep -i node
# Disk space (ensure >500MB free)
df -h .# Verify .aiox-core structure
find .aiox-core -type f | wc -l
# Expected: 200+ files
# Check for corrupted YAML
for f in .aiox-core/**/*.yaml; do npx yaml-lint "$f"; done
# Verify permissions
ls -la .aiox-core/- Run
npx aiox-core statusand note the output - Check this troubleshooting guide
- Search existing GitHub Issues
**Environment:**
- OS: [Windows 11 / macOS 14 / Ubuntu 22.04]
- Node.js version: [output of `node --version`]
- npm version: [output of `npm --version`]
- IDE: [Claude Code / Cursor / etc.]
**Steps to Reproduce:**
1. [First step]
2. [Second step]
3. [Error occurs]
**Expected Behavior:**
[What should happen]
**Actual Behavior:**
[What actually happens]
**Error Output:**
[Paste full error message here]
**Additional Context:**
[Any other relevant information]
- GitHub Issues: aiox-core/issues
- Documentation: docs/installation/
- FAQ: faq.md