Synkra AIOX Troubleshooting Guide

🌐 EN | PT | ES

This comprehensive guide helps you diagnose and resolve common issues with Synkra AIOX.

Quick Diagnostics
Installation Issues
Meta-Agent Problems
Memory Layer Issues
Performance Problems
API and Integration Issues
Security and Permission Errors
Platform-Specific Issues
Advanced Troubleshooting
Getting Help

Quick Diagnostics

Run System Doctor

Always start with the built-in diagnostics:

# Basic diagnostic
npx aiox-core doctor

# Auto-fix common issues
npx aiox-core doctor --fix

# Verbose output
npx aiox-core doctor --verbose

# Check specific component
npx aiox-core doctor --component memory-layer

Common Quick Fixes

# Clear all caches
*memory clear-cache

# Rebuild memory index
*memory rebuild

# Reset configuration
*config --reset

# Update to latest version
npx aiox-core update

Installation Issues

Issue: NPX command not found

Symptoms:

bash: npx: command not found

Solution:

# Check npm version
npm --version

# If npm < 5.2, install npx globally
npm install -g npx

# Or use npm directly
npm exec aiox-core init my-project

Issue: Installation fails with permission errors

Symptoms:

Error: EACCES: permission denied

Solutions:

Option 1: Fix npm permissions (Recommended)

# Create npm directory
mkdir ~/.npm-global

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

# Add to PATH (add to ~/.bashrc or ~/.zshrc)
export PATH=~/.npm-global/bin:$PATH

# Reload shell
source ~/.bashrc

Option 2: Use different directory

# Install in user directory
cd ~
npx aiox-core init my-project

Issue: Node.js version error

Symptoms:

Error: Node.js version 18.0.0 or higher required

Solution:

# Check current version
node --version

# Update Node.js
# macOS (using Homebrew)
brew upgrade node

# Windows (using Chocolatey)
choco upgrade nodejs

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

# Or use nvm (Node Version Manager)
nvm install 18
nvm use 18

Issue: Installation hangs or times out

Symptoms:

Installation stuck at "Installing dependencies..."
Network timeout errors

Solutions:

# Use different registry
npm config set registry https://registry.npmjs.org/

# Clear npm cache
npm cache clean --force

# Increase timeout
npm config set fetch-timeout 60000

# Skip dependency installation
npx aiox-core init my-project --skip-install

# Then install manually
cd my-project
npm install --verbose

Issue: Disk space error

Symptoms:

Error: ENOSPC: no space left on device

Solution:

# Check available space
df -h

# Clean npm cache
npm cache clean --force

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

# Clean temporary files
# macOS/Linux
rm -rf /tmp/npm-*

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

Meta-Agent Problems

Issue: Meta-agent won't start

Symptoms:

Error: Failed to initialize meta-agent

Solutions:

Check configuration:

# Verify config exists
ls -la .aiox/config.json

# Validate configuration
npx aiox-core doctor --component config

# Reset if corrupted
rm .aiox/config.json
npx aiox-core doctor --fix

Check dependencies:

# Reinstall core dependencies
npm install

# Verify agent files
ls -la agents/

Check environment:

# Verify environment variables
cat .env

# Ensure API keys are set
echo "OPENAI_API_KEY=your-key" >> .env

Issue: Commands not recognized

Symptoms:

Unknown command: *create-agent

Solutions:

Verify agent activation:

# List active agents
*list-agents --active

# Activate meta-agent
*activate meta-agent

# Verify command availability
*help

Check command syntax:

# Correct syntax uses asterisk
*create-agent my-agent  # ✓ Correct
create-agent my-agent   # ✗ Wrong

Reload agents:

# Reload all agents
*reload-agents

# Or restart meta-agent
exit
npx aiox-core

Issue: Agent creation fails

Symptoms:

Error: Failed to create agent

Solutions:

Check permissions:

# Verify write permissions
ls -la agents/

# Fix permissions
chmod 755 agents/

Validate agent name:

# Valid names: lowercase, hyphens
*create-agent my-agent      # ✓ Good
*create-agent MyAgent       # ✗ Bad (uppercase)
*create-agent my_agent      # ✗ Bad (underscore)
*create-agent my-agent-2    # ✓ Good

Check for duplicates:

# List existing agents
*list-agents

# Remove duplicate if exists
rm agents/duplicate-agent.yaml

Memory Layer Issues

Issue: Memory search returns no results

Symptoms:

Semantic search finds nothing
Pattern recognition fails

Solutions:

Rebuild memory index:

# Clear and rebuild
*memory clear-cache
*memory rebuild --verbose

# Wait for indexing
# Check progress
*memory status

Verify memory configuration:

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

# Reset to defaults
*memory reset-config

Check index integrity:

# Run memory diagnostics
*memory diagnose

# Repair if needed
*memory repair

Issue: Memory layer using too much RAM

Symptoms:

High memory usage
System slowdown

Solutions:

Adjust memory settings:

// Edit .aiox/memory-config.json
{
  "maxDocuments": 5000,      // Reduce from 10000
  "chunkSize": 256,          // Reduce from 512
  "cacheSize": 100,          // Reduce from 1000
  "enableCompression": true  // Enable compression
}

Clear old data:

# Remove old entries
*memory prune --older-than "30 days"

# Optimize storage
*memory optimize

Use memory limits:

# Set memory limit
export NODE_OPTIONS="--max-old-space-size=1024"

# Run with limited memory
npx aiox-core

Issue: LlamaIndex errors

Symptoms:

Error: LlamaIndex initialization failed

Solutions:

Check API keys:

# Verify OpenAI key for embeddings
echo $OPENAI_API_KEY

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

Use local embeddings:

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

Reinstall LlamaIndex:

npm uninstall llamaindex
npm install llamaindex@latest

Performance Problems

Issue: Slow command execution

Symptoms:

Commands take > 5 seconds
UI feels sluggish

Solutions:

Profile performance:

# Enable profiling
*debug enable --profile

# Run slow command
*analyze-framework

# View profile
*debug show-profile

Optimize configuration:

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

Clean up resources:

# Clear caches
*cache clear --all

# Remove unused agents
*cleanup-agents

# Optimize database
*optimize-db

Issue: High CPU usage

Symptoms:

Fan noise
System lag
High CPU in task manager

Solutions:

Limit concurrent operations:

# Set operation limits
*config --set performance.maxConcurrent 2
*config --set performance.cpuThreshold 80

Disable real-time features:

# Disable real-time indexing
*config --set memory.realTimeIndex false

# Use batch processing
*config --set performance.batchMode true

Check for runaway processes:

# List all processes
*debug processes

# Kill stuck process
*debug kill-process <pid>

API and Integration Issues

Issue: API key not working

Symptoms:

Error: Invalid API key
Error: 401 Unauthorized

Solutions:

Verify API key format:

# OpenAI
echo $OPENAI_API_KEY
# Should start with "sk-"

# Anthropic
echo $ANTHROPIC_API_KEY
# Should start with "sk-ant-"

Test API directly:

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

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

Check rate limits:

# View current usage
*api-status

# Switch to different provider
*config --set ai.provider anthropic

Issue: Network connection errors

Symptoms:

Error: ECONNREFUSED
Error: getaddrinfo ENOTFOUND

Solutions:

Check proxy settings:

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

# Test connection
curl -I https://api.openai.com

Use offline mode:

# Enable offline mode
*config --set offline true

# Use local models
*config --set ai.provider local

Configure timeouts:

# Increase timeouts
*config --set network.timeout 30000
*config --set network.retries 3

Security and Permission Errors

Issue: Permission denied errors

Symptoms:

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

Solutions:

Fix file permissions:

# Fix project permissions
chmod -R 755 .
chmod 600 .env

# Fix specific directories
chmod 755 agents/ tasks/ workflows/

Check file ownership:

# View ownership
ls -la

# Fix ownership (Linux/macOS)
sudo chown -R $(whoami) .

Run with correct user:

# Don't use sudo for npm
npm install  # ✓ Good
sudo npm install  # ✗ Bad

Issue: Sensitive data exposed

Symptoms:

API keys visible in logs
Credentials in error messages

Solutions:

Secure environment variables:

# Check .gitignore
cat .gitignore | grep .env

# Add if missing
echo ".env" >> .gitignore
echo ".aiox/logs/" >> .gitignore

Enable secure mode:

# Enable security features
*config --set security.maskSensitive true
*config --set security.secureLogging true

Rotate compromised keys:

# Generate new keys from providers
# Update .env file
# Clear logs
rm -rf .aiox/logs/*

Platform-Specific Issues

Windows Issues

Issue: Path too long errors

Error: ENAMETOOLONG

Solution:

# Enable long paths (Run as Administrator)
New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" `
  -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force

# Or use shorter paths
cd C:\
npx aiox-core init myapp

Issue: Scripts disabled

Error: Scripts is disabled on this system

Solution:

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

macOS Issues

Issue: Command Line Tools missing

Error: xcrun: error: invalid active developer path

Solution:

# Install Xcode Command Line Tools
xcode-select --install

Issue: Gatekeeper blocks execution

Error: "aiox-core" cannot be opened

Solution:

# Allow execution
sudo spctl --master-disable

# Or remove quarantine
xattr -d com.apple.quarantine /usr/local/bin/aiox-core

Linux Issues

Issue: Missing dependencies

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

Solution:

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

# RHEL/CentOS
sudo yum install openssl-devel

# Arch
sudo pacman -S openssl

Advanced Troubleshooting

Enable Debug Mode

# Full debug output
export DEBUG=aiox:*
npx aiox-core

# Specific components
export DEBUG=aiox:memory,aiox:agent

Analyze Logs

# View recent logs
tail -f .aiox/logs/aiox.log

# Search for errors
grep -i error .aiox/logs/*.log

# View structured logs
*logs --format json --level error

Create Diagnostic Report

# Generate full diagnostic
npx aiox-core doctor --report diagnostic.json

# Include system info
npx aiox-core info --detailed >> diagnostic.json

# Create support bundle
tar -czf aiox-support.tar.gz .aiox/logs diagnostic.json

Performance Profiling

// Enable profiling in config
{
  "debug": {
    "profiling": true,
    "profileOutput": ".aiox/profiles/"
  }
}

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

Memory Dump Analysis

# Create heap snapshot
*debug heap-snapshot

# Analyze memory usage
*debug memory-report

# Find memory leaks
*debug find-leaks

Getting Help

Before Asking for Help

Run diagnostics:

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

Collect information:
- Node.js version: node --version
- NPM version: npm --version
- OS and version: uname -a or ver
- AIOX version: npx aiox-core version
Check existing issues:
- GitHub Issues
- Discussions

Community Support

Discord: Join our server
- #help - General help
- #bugs - Bug reports
- #meta-agent - Meta-agent specific
GitHub Discussions: Technical questions and feature requests
Stack Overflow: Tag questions with aiox-core

Reporting Bugs

Create detailed bug reports:

## Environment
- OS: macOS 13.0
- Node: 18.17.0
- AIOX: 1.0.0

## Steps to Reproduce
1. Run `npx aiox-core init test`
2. Select "enterprise" template
3. Error occurs during installation

## Expected Behavior
Installation completes successfully

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

## Logs
[Attach diagnostic.log]

## Additional Context
Using corporate proxy

Emergency Recovery

If all else fails:

# Backup current state
cp -r .aiox .aiox.backup

# Complete reset
rm -rf .aiox node_modules package-lock.json
npm cache clean --force

# Fresh install
npm install
npx aiox-core doctor --fix

# Restore data if needed
cp .aiox.backup/memory.db .aiox/

Remember: Most issues can be resolved with:

npx aiox-core doctor --fix
Clearing caches
Updating to latest version
Checking permissions

When in doubt, the community is here to help! 🚀

Synkra AIOX Troubleshooting Guide

Table of Contents

Quick Diagnostics

Run System Doctor

Common Quick Fixes

Installation Issues

Issue: NPX command not found

Issue: Installation fails with permission errors

Issue: Node.js version error

Issue: Installation hangs or times out

Issue: Disk space error

Meta-Agent Problems

Issue: Meta-agent won't start

Issue: Commands not recognized

Issue: Agent creation fails

Memory Layer Issues

Issue: Memory search returns no results

Issue: Memory layer using too much RAM

Issue: LlamaIndex errors

Performance Problems

Issue: Slow command execution

Issue: High CPU usage

API and Integration Issues

Issue: API key not working

Issue: Network connection errors

Security and Permission Errors

Issue: Permission denied errors

Issue: Sensitive data exposed

Platform-Specific Issues

Windows Issues

Issue: Path too long errors

Issue: Scripts disabled

macOS Issues

Issue: Command Line Tools missing

Issue: Gatekeeper blocks execution

Linux Issues

Issue: Missing dependencies

Advanced Troubleshooting

Enable Debug Mode

Analyze Logs

Create Diagnostic Report

Performance Profiling

Memory Dump Analysis

Getting Help

Before Asking for Help

Community Support

Reporting Bugs

Emergency Recovery