Guia de Solução de Problemas do Synkra AIOS

npx @synkra/aios-core status

'npx' is not recognized as an internal or external command

# Verifique se o Node.js está instalado
node --version
 
# Se não estiver instalado:
# Windows: Baixe em https://nodejs.org/
# macOS: brew install node
# Linux: nvm install 18
 
# Verifique se o npm está disponível
npm --version
 
# Se o npm estiver faltando, reinstale o Node.js

⚠️  Inappropriate Installation Directory Detected

Current directory: /Users/username

Synkra AIOS should be installed in your project directory,
not in your home directory or temporary locations.

# Navegue para o diretório do seu projeto primeiro
cd /path/to/your/project
 
# Então execute o instalador
npx @synkra/aios-core install

Installation failed: ENOENT: no such file or directory

# Crie o diretório primeiro
mkdir -p /path/to/your/project
 
# Navegue até ele
cd /path/to/your/project
 
# Execute o instalador
npx @synkra/aios-core install

Error: Synkra AIOS requires Node.js 18.0.0 or higher
Current version: 14.17.0

# Verifique a versão atual
node --version
 
# Atualize usando nvm (recomendado)
nvm install 18
nvm use 18
 
# Ou baixe o LTS mais recente em nodejs.org

npm ERR! code E404
npm ERR! 404 Not Found - GET https://registry.npmjs.org/@synkra/aios-core

# Limpe o cache npm
npm cache clean --force
 
# Verifique o registro
npm config get registry
# Deve ser: https://registry.npmjs.org/
 
# Se estiver usando registro customizado, resete para o padrão
npm config set registry https://registry.npmjs.org/
 
# Tente a instalação novamente
npx @synkra/aios-core install

npm ERR! EACCES: permission denied, mkdir '/usr/local/lib/node_modules'

# Opção 1: Corrigir permissões npm (Linux/macOS)
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH
# Adicione a linha de export ao ~/.bashrc ou ~/.zshrc
 
# Opção 2: Usar npx ao invés de instalação global (recomendado)
npx @synkra/aios-core install
 
# Opção 3: Usar nvm para gerenciar Node.js
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 18

npm ERR! code ETIMEDOUT
npm ERR! errno ETIMEDOUT
npm ERR! network request to https://registry.npmjs.org/@synkra/aios-core failed

# Verifique se o registro npm está acessível
curl -I https://registry.npmjs.org/
 
# Se estiver atrás de um proxy, configure o npm
npm config set proxy http://proxy.company.com:8080
npm config set https-proxy http://proxy.company.com:8080
 
# Se estiver usando inspeção SSL corporativa, desabilite SSL estrito (use com cuidado)
npm config set strict-ssl false
 
# Tente novamente com logging verboso
npm install @synkra/aios-core --verbose

npm ERR! code UNABLE_TO_GET_ISSUER_CERT_LOCALLY
npm ERR! unable to get local issuer certificate

# Adicione o certificado CA da sua empresa
npm config set cafile /path/to/your/certificate.pem
 
# Ou desabilite SSL estrito (use apenas se você confia na sua rede)
npm config set strict-ssl false
 
# Verifique e tente novamente
npm config get strict-ssl
npx @synkra/aios-core install

npm ERR! network socket hang up
npm ERR! network This is a problem related to network connectivity.

# Tente usar DNS diferente
# Windows: Painel de Controle > Rede > DNS = 8.8.8.8, 8.8.4.4
# Linux: echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf
 
# Limpe o cache DNS
# Windows: ipconfig /flushdns
# macOS: sudo dscacheutil -flushcache
# Linux: sudo systemd-resolve --flush-caches
 
# Tente novamente com timeout maior
npm config set fetch-timeout 60000
npx @synkra/aios-core install

Error: EPERM: operation not permitted, unlink '/path/to/file'

# Windows: Feche todas as instâncias de IDE, então:
taskkill /f /im node.exe
 
# macOS/Linux: Verifique processos bloqueando
lsof +D /path/to/project
 
# Mate qualquer processo segurando arquivos
kill -9 <PID>
 
# Tente a instalação novamente
npx @synkra/aios-core install

Error: EROFS: read-only file system

# Verifique se o sistema de arquivos permite escrita
touch /path/to/project/test.txt
# Se isso falhar, o diretório é somente leitura
 
# Verifique opções de montagem
mount | grep /path/to/project
 
# Instale em um diretório com permissão de escrita
cd ~/projects/my-project
npx @synkra/aios-core install

Error: ENOTEMPTY: directory not empty, rmdir '.aios-core'

# Faça backup da instalação existente
mv .aios-core .aios-core.backup
 
# Execute o instalador com flag force
npx @synkra/aios-core install --force-upgrade
 
# Se necessário, restaure arquivos customizados do backup
cp .aios-core.backup/custom-files/* .aios-core/

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

# Verifique a política atual
Get-ExecutionPolicy
 
# Defina para RemoteSigned (recomendado)
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
 
# Ou use CMD ao invés de PowerShell
cmd
npx @synkra/aios-core install

Error: ENAMETOOLONG: name too long

# Habilite caminhos longos no Windows 10/11
# Execute como Administrador:
reg add "HKLM\SYSTEM\CurrentControlSet\Control\FileSystem" /v LongPathsEnabled /t REG_DWORD /d 1 /f
 
# Ou use um caminho de projeto mais curto
cd C:\dev\proj
npx @synkra/aios-core install

bash: npm: command not found

# Adicione Node.js ao path do Git Bash
# Em ~/.bashrc ou ~/.bash_profile:
export PATH="$PATH:/c/Program Files/nodejs"
 
# Ou use Windows Terminal/CMD/PowerShell ao invés

xcode-select: error: command line tools are not installed

# Instale Xcode Command Line Tools
xcode-select --install
 
# Siga o diálogo de instalação
# Então tente novamente
npx @synkra/aios-core install

Error: Unsupported architecture: arm64

# A maioria dos pacotes funciona nativamente, mas se problemas persistirem:
 
# Instale Rosetta 2 para compatibilidade x86
softwareupdate --install-rosetta
 
# Use versão x86 do Node.js (se necessário)
arch -x86_64 /bin/bash
nvm install 18
npx @synkra/aios-core install

Error: Cannot find module '../build/Release/sharp-linux-x64.node'

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install -y build-essential libvips-dev
 
# Fedora/RHEL
sudo dnf install vips-devel
 
# Limpe o cache npm e reinstale
npm cache clean --force
npx @synkra/aios-core install

Error: /lib/x86_64-linux-gnu/libc.so.6: version `GLIBC_2.28' not found

# Verifique a versão do GLIBC
ldd --version
 
# Se a versão for muito antiga, use Node.js LTS para sua distro:
# Ubuntu 18.04: Use Node.js 16 (máximo suportado)
nvm install 16
nvm use 16
 
# Ou atualize sua distribuição Linux

Error: Agent 'dev' not found in .aios-core/agents/

# Verifique se os arquivos de agentes existem
ls .aios-core/agents/
 
# Se estiverem faltando, reinstale o core
npx @synkra/aios-core install --full
 
# Verifique se core-config.yaml é válido
cat .aios-core/core-config.yaml

YAMLException: bad indentation of a mapping entry

# Valide a sintaxe YAML
npx yaml-lint .aios-core/agents/dev.md
 
# Correções comuns:
# - Use espaços, não tabs
# - Certifique-se de indentação consistente (2 espaços)
# - Verifique caracteres especiais em strings (use aspas)
 
# Reinstale para obter arquivos de agentes limpos
mv .aios-core/agents/dev.md .aios-core/agents/dev.md.backup
npx @synkra/aios-core install --full

# Verifique status da instalação AIOS
npx @synkra/aios-core status
 
# Liste Squads disponíveis
npx @synkra/aios-core install
 
# Atualize instalação existente
npx @synkra/aios-core update
 
# Mostre logging verboso
npx @synkra/aios-core install --verbose

# Versões do Node.js e npm
node --version && npm --version
 
# Configuração npm
npm config list
 
# Variáveis de ambiente
printenv | grep -i npm
printenv | grep -i node
 
# Espaço em disco (certifique-se de ter >500MB livres)
df -h .

# Verifique estrutura .aios-core
find .aios-core -type f | wc -l
# Esperado: 200+ arquivos
 
# Verifique YAML corrompido
for f in .aios-core/**/*.yaml; do npx yaml-lint "$f"; done
 
# Verifique permissões
ls -la .aios-core/

**Ambiente:**
- SO: [Windows 11 / macOS 14 / Ubuntu 22.04]
- Versão Node.js: [saída de `node --version`]
- Versão npm: [saída de `npm --version`]
- IDE: [Claude Code / Cursor / etc.]

**Passos para Reproduzir:**
1. [Primeiro passo]
2. [Segundo passo]
3. [Erro ocorre]

**Comportamento Esperado:**
[O que deveria acontecer]

**Comportamento Atual:**
[O que realmente acontece]

**Saída de Erro:**

**Contexto Adicional:**
[Qualquer outra informação relevante]