AKIOS Logo AKIOS
EN | FR

Debugging & Troubleshooting

Quick solutions to common AKIOS issues. Most problems are configuration-related and easy to fix.

Quick Diagnosis

Start here when something's wrong:

# Check overall status
akios status

# View recent logs
akios logs --limit 10

# Run diagnostics
akios doctor

# Enable debug mode
akios --debug status

Note: Since v1.0.10, AKIOS uses Python's logging module with structured JSON output. Set AKIOS_LOG_LEVEL=DEBUG for maximum detail. Log entries include timestamp, level, module, and message.

Installation Issues

SIGTRAP Crash When Running with sudo (Fixed in v1.0.5)

If you experience a SIGTRAP crash when running sudo akios run, upgrade to v1.0.5:

sudo pip3 install --upgrade akios

Cause: The seccomp BPF filter was rejecting essential syscalls during privileged execution. This is fixed in v1.0.5.

"akios: command not found"

Pip installation:

# Check if installed
pip show akios

# Reinstall if needed
pip uninstall akios
pip install akios>=1.0.15

# Check PATH
which akios

Docker wrapper:

# Make executable
chmod +x akios

# Use from current directory
./akios --version

"Docker daemon not running"

# Start Docker Desktop (macOS/Windows)

# Or on Linux
sudo systemctl start docker

# Test Docker
docker run hello-world

"Permission denied" (Docker)

# Add user to docker group (Linux)
sudo usermod -aG docker $USER

# Logout and login again

# Or use sudo (less secure)
sudo docker run...

Configuration Issues

"API key not found" or "Invalid API key"

# Run setup wizard to fix
akios setup --force

# Or manually edit .env
nano .env

# Check what AKIOS sees
akios status --verbose

"Invalid provider/model combination"

Supported combinations:

  • OpenAI: gpt-3.5-turbo, gpt-4, gpt-4-turbo, gpt-4o, gpt-4o-mini
  • Anthropic: claude-3.5-haiku, claude-3.5-sonnet
  • Grok: grok-3
  • Mistral: mistral-small, mistral-medium, mistral-large
  • Gemini: gemini-1.0-pro, gemini-1.5-pro, gemini-1.5-flash
# Fix in .env
AKIOS_LLM_PROVIDER=grok
AKIOS_LLM_MODEL=grok-3

"Configuration validation failed"

# Check config syntax
python3 -c "import yaml; yaml.safe_load(open('config.yaml'))"

# Or just reset
akios setup --force

".env file corrupted"

Common issues the wizard detects:

  • grokopenai → Should be grok
  • tru → Should be true
  • Missing API keys
# Let wizard fix it
akios setup --force

Workflow Execution Issues

"Template not found"

# List available templates
akios templates list

# Check file exists
ls templates/

# Use correct path
akios run templates/hello-workflow.yml

"Template steps silently lost" (fixed v1.0.14)

Complex multi-step templates could silently lose steps during rendering. This is fixed in v1.0.14 — upgrade to the latest version.

"AWS Bedrock throttling (429)" (fixed v1.0.15)

Bedrock API calls returning 429 (Too Many Requests) now automatically retry with exponential backoff. If you still hit throttling, reduce the rate limit or request a quota increase in AWS console.

"Unknown env vars crash startup" (fixed v1.0.15)

Extra environment variables in .env no longer crash Pydantic settings validation. Upgrade to v1.0.15+.

"Workflow validation failed"

Each step needs:

  • agent - Which agent to use
  • action - What action to perform
  • parameters - Action-specific settings

Allowed agents: llm, http, filesystem, tool_executor

"Path not allowed" (Filesystem Agent)

Only these directories are accessible:

  • ./workflows/
  • ./templates/
  • ./data/input/
  • ./data/output/
# Move file to allowed location
mv myfile.txt data/input/

"Network access blocked" (HTTP Agent)

# Enable network in config.yaml
network_access_allowed: true

# Or use environment variable
export AKIOS_NETWORK_ACCESS_ALLOWED=1

"Budget exceeded"

# Check current usage
akios status --budget

# Increase limit
export AKIOS_BUDGET_LIMIT_PER_RUN=5.0

# Or edit config.yaml
# budget_limit_per_run: 5.0

Docker-Specific Issues

"Docker hangs in CI/CD" (fixed v1.0.14)

Docker commands hang waiting for TTY input in non-interactive environments.

Fix: Use the --non-interactive flag:

akios run workflow.yml --non-interactive

Or set the environment variable:

AKIOS_NON_INTERACTIVE=1 akios run workflow.yml

"seccomp blocks virtualenv creation" (fixed v1.0.14)

On some Linux systems, seccomp filters prevent Python virtualenv creation inside the sandbox.

Fix: AKIOS now shows a clear error message with guidance. Create your virtualenv before entering the cage, or use --no-sandbox for development.

"Docker image outdated"

# Pull latest image
docker pull akiosai/akios:v1.0.15

# Or force pull with wrapper
AKIOS_FORCE_PULL=1 ./akios status

"Container exits immediately"

# Check logs
akios logs --limit 10

# Run with debug
akios --debug run workflow.yml

"File operations slow" (macOS/Windows)

  • Update Docker Desktop to latest version
  • Check Docker resource settings
  • Consider native Linux for maximum performance
  • Expected performance: Docker startup 0.5–0.8s (vs 0.4–0.5s native), memory 60–80MB (vs 40–60MB native)

"Audit logs not persisting in Docker"

Docker containers use memory-buffered writes. To ensure persistence:

# Mount a host directory for audit logs
docker run --rm -v $(pwd)/audit:/app/audit akiosai/akios:v1.0.15 run workflow.yml

# Or use tmpfs for better performance
docker run --rm --tmpfs /app/audit akiosai/akios:v1.0.15 run workflow.yml

Security Issues

"Security validation failed"

On Linux:

  • Ensure kernel >= 5.4
  • Check seccomp support
  • Install libseccomp-dev

On macOS/Windows:

  • Use Docker (provides strong security)
  • Install Docker Desktop
# Check your security status
akios status --security

"PII detected in logs"

This shouldn't happen! Check:

# Verify PII redaction is on
akios status --security
# Should show: PII Protection: Active

If PII is leaking, report to security@akioud.ai

Performance Issues

"Workflow running slow"

# Check resource usage
akios status --verbose

# Increase limits in config.yaml
cpu_limit: 0.9
memory_limit_mb: 512

"High memory usage"

# Reduce memory limit
memory_limit_mb: 128

# Process smaller files
# Clean old runs
akios clean --old-runs 7

Emergency Recovery

If everything is broken:

# 1. Stop any running workflows
pkill -f akios

# 2. Backup your data
cp -r data/ data.backup

# 3. Reset configuration
akios setup --force

# 4. Clean old runs
akios clean --old-runs 1

# 5. Test with simple workflow
akios run templates/hello-workflow.yml

Getting More Help

Enable Debug Mode

# Debug flag
akios --debug run workflow.yml

# Or environment variable
export AKIOS_DEBUG=1
akios run workflow.yml

Check Logs

# Recent logs
akios logs --limit 20

# Error logs only
akios logs --level ERROR

# Audit trail
tail -20 audit/audit_events.jsonl

Run Diagnostics

# Full diagnostics
akios doctor

# JSON output for bug reports
akios doctor --json > diagnostics.json

Still Stuck?

Include in bug reports:

  • akios --version
  • akios doctor --json
  • Steps to reproduce
  • Expected vs actual behavior

Related Docs

ESC