Guia de Solucion de Problemas de Synkra AIOX

🌐 EN | PT | ES

Esta guia completa te ayuda a diagnosticar y resolver problemas comunes con Synkra AIOX.

Tabla de Contenidos

Diagnosticos Rapidos
Problemas de Instalacion
Problemas del Meta-Agente
Problemas de la Capa de Memoria
Problemas de Rendimiento
Problemas de API e Integracion
Errores de Seguridad y Permisos
Problemas Especificos de Plataforma
Solucion de Problemas Avanzada
Obtener Ayuda

Diagnosticos Rapidos

Ejecutar el Doctor del Sistema

Siempre comienza con los diagnosticos integrados:

# Diagnostico basico
npx aiox-core doctor

# Auto-corregir problemas comunes
npx aiox-core doctor --fix

# Salida detallada
npx aiox-core doctor --verbose

# Verificar componente especifico
npx aiox-core doctor --component memory-layer

Correcciones Rapidas Comunes

# Limpiar todos los caches
*memory clear-cache

# Reconstruir indice de memoria
*memory rebuild

# Restablecer configuracion
*config --reset

# Actualizar a la ultima version
npx aiox-core update

Problemas de Instalacion

Problema: Comando NPX no encontrado

Sintomas:

bash: npx: command not found

Solucion:

# Verificar version de npm
npm --version

# Si npm < 5.2, instalar npx globalmente
npm install -g npx

# O usar npm directamente
npm exec aiox-core init my-project

Problema: Instalacion falla con errores de permisos

Sintomas:

Error: EACCES: permission denied

Soluciones:

Opcion 1: Corregir permisos de npm (Recomendado)

# Crear directorio npm
mkdir ~/.npm-global

# Configurar npm
npm config set prefix '~/.npm-global'

# Agregar al PATH (agregar a ~/.bashrc o ~/.zshrc)
export PATH=~/.npm-global/bin:$PATH

# Recargar shell
source ~/.bashrc

Opcion 2: Usar directorio diferente

# Instalar en directorio de usuario
cd ~
npx aiox-core init my-project

Problema: Error de version de Node.js

Sintomas:

Error: Node.js version 18.0.0 or higher required

Solucion:

# Verificar version actual
node --version

# Actualizar Node.js
# macOS (usando Homebrew)
brew upgrade node

# Windows (usando Chocolatey)
choco upgrade nodejs

# Linux (usando NodeSource)
curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs

# O usar nvm (Node Version Manager)
nvm install 18
nvm use 18

Problema: Instalacion se cuelga o agota tiempo de espera

Sintomas:

Instalacion atascada en "Installing dependencies..."
Errores de tiempo de espera de red

Soluciones:

# Usar registro diferente
npm config set registry https://registry.npmjs.org/

# Limpiar cache de npm
npm cache clean --force

# Aumentar tiempo de espera
npm config set fetch-timeout 60000

# Omitir instalacion de dependencias
npx aiox-core init my-project --skip-install

# Luego instalar manualmente
cd my-project
npm install --verbose

Problema: Error de espacio en disco

Sintomas:

Error: ENOSPC: no space left on device

Solucion:

# Verificar espacio disponible
df -h

# Limpiar cache de npm
npm cache clean --force

# Eliminar node_modules antiguos
find . -name "node_modules" -type d -prune -exec rm -rf '{}' +

# Limpiar archivos temporales
# macOS/Linux
rm -rf /tmp/npm-*

# Windows
rmdir /s %TEMP%\npm-*

Problemas del Meta-Agente

Problema: El meta-agente no inicia

Sintomas:

Error: Failed to initialize meta-agent

Soluciones:

Verificar configuracion:

# Verificar que config existe
ls -la .aiox/config.json

# Validar configuracion
npx aiox-core doctor --component config

# Restablecer si esta corrupto
rm .aiox/config.json
npx aiox-core doctor --fix

Verificar dependencias:

# Reinstalar dependencias principales
npm install

# Verificar archivos de agentes
ls -la agents/

Verificar entorno:

# Verificar variables de entorno
cat .env

# Asegurar que API keys estan configuradas
echo "OPENAI_API_KEY=your-key" >> .env

Problema: Comandos no reconocidos

Sintomas:

Unknown command: *create-agent

Soluciones:

Verificar activacion del agente:

# Listar agentes activos
*list-agents --active

# Activar meta-agente
*activate meta-agent

# Verificar disponibilidad de comandos
*help

Verificar sintaxis de comandos:

# Sintaxis correcta usa asterisco
*create-agent my-agent  # Correcto
create-agent my-agent   # Incorrecto

Recargar agentes:

# Recargar todos los agentes
*reload-agents

# O reiniciar meta-agente
exit
npx aiox-core

Problema: Creacion de agente falla

Sintomas:

Error: Failed to create agent

Soluciones:

Verificar permisos:

# Verificar permisos de escritura
ls -la agents/

# Corregir permisos
chmod 755 agents/

Validar nombre del agente:

# Nombres validos: minusculas, guiones
*create-agent my-agent      # Bueno
*create-agent MyAgent       # Malo (mayusculas)
*create-agent my_agent      # Malo (guion bajo)
*create-agent my-agent-2    # Bueno

Verificar duplicados:

# Listar agentes existentes
*list-agents

# Eliminar duplicado si existe
rm agents/duplicate-agent.yaml

Problemas de la Capa de Memoria

Problema: Busqueda de memoria no retorna resultados

Sintomas:

Busqueda semantica no encuentra nada
Reconocimiento de patrones falla

Soluciones:

Reconstruir indice de memoria:

# Limpiar y reconstruir
*memory clear-cache
*memory rebuild --verbose

# Esperar indexacion
# Verificar progreso
*memory status

Verificar configuracion de memoria:

# Verificar config
cat .aiox/memory-config.json

# Restablecer a valores por defecto
*memory reset-config

Verificar integridad del indice:

# Ejecutar diagnosticos de memoria
*memory diagnose

# Reparar si es necesario
*memory repair

Problema: Capa de memoria usando demasiada RAM

Sintomas:

Alto uso de memoria
Ralentizacion del sistema

Soluciones:

Ajustar configuracion de memoria:

// Editar .aiox/memory-config.json
{
  "maxDocuments": 5000,      // Reducir de 10000
  "chunkSize": 256,          // Reducir de 512
  "cacheSize": 100,          // Reducir de 1000
  "enableCompression": true  // Habilitar compresion
}

Limpiar datos antiguos:

# Eliminar entradas antiguas
*memory prune --older-than "30 days"

# Optimizar almacenamiento
*memory optimize

Usar limites de memoria:

# Establecer limite de memoria
export NODE_OPTIONS="--max-old-space-size=1024"

# Ejecutar con memoria limitada
npx aiox-core

Problema: Errores de LlamaIndex

Sintomas:

Error: LlamaIndex initialization failed

Soluciones:

Verificar API keys:

# Verificar clave de OpenAI para embeddings
echo $OPENAI_API_KEY

# Probar acceso a API
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

Usar embeddings locales:

// .aiox/memory-config.json
{
  "embedModel": "local",
  "localModelPath": "./models/embeddings"
}

Reinstalar LlamaIndex:

npm uninstall llamaindex
npm install llamaindex@latest

Problemas de Rendimiento

Problema: Ejecucion lenta de comandos

Sintomas:

Comandos toman > 5 segundos
UI se siente lenta

Soluciones:

Perfilar rendimiento:

# Habilitar perfilado
*debug enable --profile

# Ejecutar comando lento
*analyze-framework

# Ver perfil
*debug show-profile

Optimizar configuracion:

// .aiox/config.json
{
  "performance": {
    "enableCache": true,
    "parallelOperations": 4,
    "lazyLoading": true,
    "indexUpdateFrequency": "hourly"
  }
}

Limpiar recursos:

# Limpiar caches
*cache clear --all

# Eliminar agentes no usados
*cleanup-agents

# Optimizar base de datos
*optimize-db

Problema: Alto uso de CPU

Sintomas:

Ruido del ventilador
Lag del sistema
CPU alto en administrador de tareas

Soluciones:

Limitar operaciones concurrentes:

# Establecer limites de operacion
*config --set performance.maxConcurrent 2
*config --set performance.cpuThreshold 80

Deshabilitar funciones en tiempo real:

# Deshabilitar indexacion en tiempo real
*config --set memory.realTimeIndex false

# Usar procesamiento por lotes
*config --set performance.batchMode true

Verificar procesos fuera de control:

# Listar todos los procesos
*debug processes

# Matar proceso atascado
*debug kill-process <pid>

Problemas de API e Integracion

Problema: API key no funciona

Sintomas:

Error: Invalid API key
Error: 401 Unauthorized

Soluciones:

Verificar formato de API key:

# OpenAI
echo $OPENAI_API_KEY
# Deberia comenzar con "sk-"

# Anthropic
echo $ANTHROPIC_API_KEY
# Deberia comenzar con "sk-ant-"

Probar API directamente:

# Probar OpenAI
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

# Probar Anthropic
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01"

Verificar limites de tasa:

# Ver uso actual
*api-status

# Cambiar a proveedor diferente
*config --set ai.provider anthropic

Problema: Errores de conexion de red

Sintomas:

Error: ECONNREFUSED
Error: getaddrinfo ENOTFOUND

Soluciones:

Verificar configuracion de proxy:

# Proxy corporativo
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080

# Probar conexion
curl -I https://api.openai.com

Usar modo offline:

# Habilitar modo offline
*config --set offline true

# Usar modelos locales
*config --set ai.provider local

Configurar tiempos de espera:

# Aumentar tiempos de espera
*config --set network.timeout 30000
*config --set network.retries 3

Errores de Seguridad y Permisos

Problema: Errores de permiso denegado

Sintomas:

Error: EACCES: permission denied
Error: Cannot write to file

Soluciones:

Corregir permisos de archivos:

# Corregir permisos del proyecto
chmod -R 755 .
chmod 600 .env

# Corregir directorios especificos
chmod 755 agents/ tasks/ workflows/

Verificar propiedad de archivos:

# Ver propiedad
ls -la

# Corregir propiedad (Linux/macOS)
sudo chown -R $(whoami) .

Ejecutar con usuario correcto:

# No usar sudo para npm
npm install  # Correcto
sudo npm install  # Incorrecto

Problema: Datos sensibles expuestos

Sintomas:

API keys visibles en logs
Credenciales en mensajes de error

Soluciones:

Asegurar variables de entorno:

# Verificar .gitignore
cat .gitignore | grep .env

# Agregar si falta
echo ".env" >> .gitignore
echo ".aiox/logs/" >> .gitignore

Habilitar modo seguro:

# Habilitar funciones de seguridad
*config --set security.maskSensitive true
*config --set security.secureLogging true

Rotar claves comprometidas:

# Generar nuevas claves desde proveedores
# Actualizar archivo .env
# Limpiar logs
rm -rf .aiox/logs/*

Problemas Especificos de Plataforma

Problemas de Windows

Problema: Errores de ruta demasiado larga

Error: ENAMETOOLONG

Solucion:

# Habilitar rutas largas (Ejecutar como Administrador)
New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" `
  -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force

# O usar rutas mas cortas
cd C:\
npx aiox-core init myapp

Problema: Scripts deshabilitados

Error: Scripts is disabled on this system

Solucion:

# Ejecutar como Administrador
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Problemas de macOS

Problema: Herramientas de Linea de Comandos faltantes

Error: xcrun: error: invalid active developer path

Solucion:

# Instalar Herramientas de Linea de Comandos de Xcode
xcode-select --install

Problema: Gatekeeper bloquea ejecucion

Error: "aiox-core" cannot be opened

Solucion:

# Permitir ejecucion
sudo spctl --master-disable

# O eliminar cuarentena
xattr -d com.apple.quarantine /usr/local/bin/aiox-core

Problemas de Linux

Problema: Dependencias faltantes

Error: libssl.so.1.1: cannot open shared object file

Solucion:

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install libssl-dev

# RHEL/CentOS
sudo yum install openssl-devel

# Arch
sudo pacman -S openssl

Solucion de Problemas Avanzada

Habilitar Modo Debug

# Salida completa de debug
export DEBUG=aiox:*
npx aiox-core

# Componentes especificos
export DEBUG=aiox:memory,aiox:agent

Analizar Logs

# Ver logs recientes
tail -f .aiox/logs/aiox.log

# Buscar errores
grep -i error .aiox/logs/*.log

# Ver logs estructurados
*logs --format json --level error

Crear Reporte de Diagnostico

# Generar diagnostico completo
npx aiox-core doctor --report diagnostic.json

# Incluir info del sistema
npx aiox-core info --detailed >> diagnostic.json

# Crear paquete de soporte
tar -czf aiox-support.tar.gz .aiox/logs diagnostic.json

Perfilado de Rendimiento

// Habilitar perfilado en config
{
  "debug": {
    "profiling": true,
    "profileOutput": ".aiox/profiles/"
  }
}

# Analizar perfil
*debug analyze-profile .aiox/profiles/latest.cpuprofile

Analisis de Volcado de Memoria

# Crear snapshot de heap
*debug heap-snapshot

# Analizar uso de memoria
*debug memory-report

# Encontrar fugas de memoria
*debug find-leaks

Obtener Ayuda

Antes de Pedir Ayuda

Ejecutar diagnosticos:

npx aiox-core doctor --verbose > diagnostic.log

Recopilar informacion:
- Version de Node.js: node --version
- Version de NPM: npm --version
- SO y version: uname -a o ver
- Version de AIOX: npx aiox-core version
Verificar issues existentes:
- GitHub Issues
- Discussions

Soporte de la Comunidad

Discord: Unete a nuestro servidor
- #help - Ayuda general
- #bugs - Reportes de bugs
- #meta-agent - Especifico del meta-agente
GitHub Discussions: Preguntas tecnicas y solicitudes de funcionalidades
Stack Overflow: Etiqueta preguntas con aiox-core

Reportando Bugs

Crea reportes de bugs detallados:

## Entorno
- SO: macOS 13.0
- Node: 18.17.0
- AIOX: 1.0.0

## Pasos para Reproducir
1. Ejecutar `npx aiox-core init test`
2. Seleccionar plantilla "enterprise"
3. Error ocurre durante instalacion

## Comportamiento Esperado
La instalacion se completa exitosamente

## Comportamiento Actual
Error: Cannot find module 'inquirer'

## Logs
[Adjuntar diagnostic.log]

## Contexto Adicional
Usando proxy corporativo

Recuperacion de Emergencia

Si todo lo demas falla:

# Respaldar estado actual
cp -r .aiox .aiox.backup

# Restablecimiento completo
rm -rf .aiox node_modules package-lock.json
npm cache clean --force

# Instalacion fresca
npm install
npx aiox-core doctor --fix

# Restaurar datos si es necesario
cp .aiox.backup/memory.db .aiox/

Recuerda: La mayoria de los problemas pueden resolverse con:

npx aiox-core doctor --fix
Limpiando caches
Actualizando a la ultima version
Verificando permisos

Cuando tengas dudas, la comunidad esta aqui para ayudar!

Uh oh!

Uh oh!

FilesExpand file tree

troubleshooting.md

Latest commit

History

troubleshooting.md

File metadata and controls

Guia de Solucion de Problemas de Synkra AIOX

Tabla de Contenidos

Diagnosticos Rapidos

Ejecutar el Doctor del Sistema

Correcciones Rapidas Comunes

Problemas de Instalacion

Problema: Comando NPX no encontrado

Problema: Instalacion falla con errores de permisos

Problema: Error de version de Node.js

Problema: Instalacion se cuelga o agota tiempo de espera

Problema: Error de espacio en disco

Problemas del Meta-Agente

Problema: El meta-agente no inicia

Problema: Comandos no reconocidos

Problema: Creacion de agente falla

Problemas de la Capa de Memoria

Problema: Busqueda de memoria no retorna resultados

Problema: Capa de memoria usando demasiada RAM

Problema: Errores de LlamaIndex

Problemas de Rendimiento

Problema: Ejecucion lenta de comandos

Problema: Alto uso de CPU

Problemas de API e Integracion

Problema: API key no funciona

Problema: Errores de conexion de red

Errores de Seguridad y Permisos

Problema: Errores de permiso denegado

Problema: Datos sensibles expuestos

Problemas Especificos de Plataforma

Problemas de Windows

Problema: Errores de ruta demasiado larga

Problema: Scripts deshabilitados

Problemas de macOS

Problema: Herramientas de Linea de Comandos faltantes

Problema: Gatekeeper bloquea ejecucion

Problemas de Linux

Problema: Dependencias faltantes

Solucion de Problemas Avanzada

Habilitar Modo Debug

Analizar Logs

Crear Reporte de Diagnostico

Perfilado de Rendimiento

Analisis de Volcado de Memoria

Obtener Ayuda

Antes de Pedir Ayuda

Soporte de la Comunidad

Reportando Bugs

Recuperacion de Emergencia