Skip to content

Latest commit

 

History

History
321 lines (227 loc) · 6.06 KB

installation-troubleshooting.md

File metadata and controls

321 lines (227 loc) · 6.06 KB

AIOS-Core Installation & Troubleshooting Guide

EN | PT | ES

Quick Start

npx aios-core@latest

This command downloads and runs the latest version of AIOS-Core installer.

System Requirements

Requirement Minimum Version Check Command
Node.js v18.0.0+ node --version
npm v9.0.0+ npm --version
npx (included with npm 5.2+) npx --version
Git Any recent version (optional) git --version

Download Links

Installation Methods

Method 1: npx (Recommended)

# Install in current directory
npx aios-core@latest

# Install with specific version
npx aios-core@2.2.0

# Show version
npx aios-core@latest --version

# Show help
npx aios-core@latest --help

Method 2: From GitHub

npx github:SynkraAI/aios-core install

Method 3: Global Installation

npm install -g aios-core
aios-core

Diagnostic Tool

If you're having installation issues, run our diagnostic tool:

Windows (CMD)

curl -o diagnose.cmd https://raw.githubusercontent.com/SynkraAI/aios-core/main/tools/quick-diagnose.cmd && diagnose.cmd

Windows (PowerShell)

irm https://raw.githubusercontent.com/SynkraAI/aios-core/main/tools/quick-diagnose.ps1 | iex

macOS/Linux

curl -fsSL https://raw.githubusercontent.com/SynkraAI/aios-core/main/tools/diagnose-installation.js | node

Common Issues & Solutions

Issue 1: "Node.js version too old"

Error:

error engine Unsupported engine
error notsup Required: {"node":">=18.0.0"}

Solution:

  1. Download Node.js LTS from https://nodejs.org/
  2. Install and restart your terminal
  3. Verify: node --version (should show v18+ or v20+)

Issue 2: "npm version too old"

Error:

npm ERR! Required: {"npm":">=9.0.0"}

Solution:

# Update npm globally
npm install -g npm@latest

# Verify
npm --version

Issue 3: "npx not found" or "npx command not recognized"

Cause: npm bin folder not in system PATH

Solution (Windows):

  1. Find npm prefix: npm config get prefix
  2. Add to PATH:
    • Press Win+X → System → Advanced system settings → Environment Variables
    • Edit "Path" under User variables
    • Add: C:\Users\YOUR_USERNAME\AppData\Roaming\npm
  3. Restart terminal

Solution (macOS/Linux):

# Add to ~/.bashrc or ~/.zshrc
export PATH="$PATH:$(npm config get prefix)/bin"

# Reload
source ~/.bashrc

Issue 4: "EACCES: permission denied"

Solution (Windows): Run terminal as Administrator

Solution (macOS/Linux):

# Fix npm permissions (recommended)
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH

# Or use nvm (best practice)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash

Issue 5: "ETIMEDOUT" or "ECONNREFUSED"

Cause: Network/firewall blocking npm registry

Solutions:

  1. Check npm registry:

    npm config get registry
# Should be: https://registry.npmjs.org/

  2. Reset registry:

    npm config set registry https://registry.npmjs.org/

  3. Test connectivity:

    npm ping

  4. Behind corporate proxy:

    npm config set proxy http://proxy.company.com:8080
npm config set https-proxy http://proxy.company.com:8080

  5. Use mirror (China):

    npm config set registry https://registry.npmmirror.com

Issue 6: "PowerShell execution policy" (Windows)

Error:

File cannot be loaded because running scripts is disabled on this system

Solution:

# Run as Administrator
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Issue 7: "Cannot find module" or "Missing dependencies"

Solution:

# Clear npm cache
npm cache clean --force

# Remove node_modules if exists
rm -rf node_modules

# Try again
npx aios-core@latest

Issue 8: "SSL/Certificate errors"

Solution:

# Temporarily disable strict SSL (not recommended for production)
npm config set strict-ssl false

# Better: Update certificates
npm config set cafile /path/to/certificate.pem

Issue 9: Package shows old version

Cause: npm cache serving old version

Solution:

# Clear npx cache
npx clear-npx-cache

# Or force fresh download
npx --ignore-existing aios-core@latest

# Or use specific version
npx aios-core@2.2.0

Environment Verification Checklist

Run these commands to verify your environment:

# 1. Check Node.js (need v18+)
node --version

# 2. Check npm (need v9+)
npm --version

# 3. Check npx
npx --version

# 4. Check npm registry access
npm view aios-core version

# 5. Test installation
npx aios-core@latest --version

Expected output:

v22.x.x (or v18+/v20+)
11.x.x (or v9+)
11.x.x (same as npm)
2.2.0
2.2.0

Getting Help

If you're still having issues:

  1. GitHub Issues: https://github.com/SynkraAI/aios-core/issues
  2. Run diagnostics: npx aios-core@latest doctor
  3. Check system info: npx aios-core@latest info

When reporting issues, please include:

  • Operating system and version
  • Node.js version (node --version)
  • npm version (npm --version)
  • Full error message
  • Output of diagnostic tool

Quick Reference

Command Description
npx aios-core@latest Install/run wizard
npx aios-core@latest --version Show version
npx aios-core@latest --help Show help
npx aios-core@latest install Install in current dir
npx aios-core@latest init <name> Create new project
npx aios-core@latest doctor Run diagnostics
npx aios-core@latest info Show system info

Last updated: December 2025 | AIOS-Core v2.2.0