Troubleshooting

Common issues and solutions when working with the AIP SDK.

🚨 Quick Fixes (Symptom → Fix Table)

Symptom

Likely cause

Fix

401 Unauthorized

Missing/invalid key

aip config set api_key ...

404 on /agents

Wrong API URL

aip config set api_url ...

Stream hangs

Proxy/corp network

set HTTP_PROXY/HTTPS_PROXY, try --no-tty

CLI looks weird

No TTY

use --view plain

Agent not found

Resource deleted

aip agents list to see what's available

Tool execution failed

Syntax error

Check tool script for Python errors

MCP connection failed

Wrong config

aip mcps test-connection --from-file ...

Import error

Wrong Python version

Use Python 3.10+

Permission denied

File permissions

Check file ownership and permissions

429 Too Many Requests

Rate limit exceeded

Retry with backoff; reduce concurrency or request size

🔍 Collect Diagnostics

Enable Debug Mode

# Use structured output for debugging
aip agents run <AGENT_ID> --input "test" --view json

# Check detailed status
aip status

# Verify configuration
aip config list

# Test individual commands with --help
aip agents --help
aip tools --help
aip mcps --help

Check System Status

# Verify connection
aip status

# Check configuration
aip config list

# List available resources
aip agents list
aip tools list
aip mcps list

🔧 Common Issues

Connection Problems

401 Unauthorized

Symptoms: Authentication errors, "Invalid API key" messages Causes: Missing or expired API key, incorrect credentials Solutions:

# Check current key
aip config list

# Set correct key
aip config set api_key "your-new-api-key"

# Verify connection
aip status

404 Not Found

Symptoms: "Endpoint not found" errors, resource not accessible Causes: Wrong API URL, service not running, incorrect endpoint Solutions:

# Check current URL
aip config list

# Set correct URL
aip config set api_url "https://correct-api-url.com"

# Test connection
aip status

Connection Refused

Symptoms: "Connection refused", "Cannot connect to host" Causes: Service not running, firewall blocking, wrong port Solutions:

Verify the AIP backend service is running
Check firewall settings and network configuration
Confirm the correct port and protocol (HTTPS)
Try connecting from a different network

TLS/SSL Certificate Errors

Symptoms: CERTIFICATE_VERIFY_FAILED, SSL handshake errors, certificate chain issues Causes: Invalid certificates, corporate CA not installed, wrong protocol Solutions:

# 1) Ensure your AIP_API_URL uses https and correct host
aip config list

# 2) If using a corporate CA, install it or set:
export REQUESTS_CA_BUNDLE=/path/to/cacert.pem
export SSL_CERT_FILE=/path/to/cacert.pem

# 3) Verify the certificate chain
openssl s_client -connect your-aip-host:443 -servername your-aip-host

Streaming Issues

Stream Hangs

Symptoms: Output stops, no response, infinite loading Causes: Network timeouts, proxy issues, TTY problems Solutions:

# Set proxy if behind corporate firewall
export HTTP_PROXY="http://proxy.company.com:8080"
export HTTPS_PROXY="http://proxy.company.com:8080"

# Exclude AIP hosts from proxy (important for internal/on-prem deployments)
export NO_PROXY="$NO_PROXY,your-aip-host,your-mcp-host"

# Try non-TTY mode
aip agents run <AGENT_ID> --input "test" --no-tty

# Use plain output
aip agents run <AGENT_ID> --input "test" --view plain

Rich Output Issues

Symptoms: Strange characters, formatting problems, display errors Causes: TTY detection issues, terminal compatibility Solutions:

# Force plain output
aip agents run <AGENT_ID> --input "test" --view plain

# Disable TTY detection
aip agents run <AGENT_ID> --input "test" --no-tty

# Use JSON output for scripting and debugging
aip agents list --view json
aip tools list --view json

Output Formatting Issues

Symptoms: Output looks wrong, can't parse results, formatting errors Causes: Wrong view format, TTY issues, terminal compatibility Solutions:

# Available view formats: rich, plain, json, md
aip agents list --view json      # JSON for scripting
aip agents list --view plain     # Simple text
aip agents list --view md        # Markdown tables
aip agents list --view rich      # Rich formatting (default)

# Use --no-tty if you're in a non-interactive environment
aip agents list --no-tty --view plain

Resource Management

Rate Limiting Issues

Symptoms: "429 Too Many Requests", rate limit exceeded errors, throttling Causes: Too many requests in short time, exceeding API limits, high concurrency Solutions:

# Implement exponential backoff
# Wait 1s, then 2s, then 4s, then 8s...

# Reduce request frequency
# Space out requests instead of sending them all at once

# Check current usage limits
aip status

# Use appropriate timeouts
aip agents run <AGENT_ID> --input "test" --timeout 60

# Consider batching operations where possible

Agent Not Found

Symptoms: "Agent not found" errors, 404 responses Causes: Agent was deleted, wrong ID, permission issues Solutions:

# List available agents
aip agents list

# Check agent details
aip agents get <AGENT_ID>

# Inspect agent details and permissions
aip agents get <AGENT_ID> --view json | jq '{id, name, type, framework, version}'

# Verify permissions and ownership
# Check if you're in the correct tenant/project context

Tool Execution Failed

Symptoms: Tool errors, execution failures, syntax errors Causes: Python syntax errors, missing dependencies, framework issues Solutions:

Check tool script for Python syntax errors
Verify all required dependencies are available
Test tool script independently
Check framework compatibility

Permission Issues

Symptoms: "Permission denied", "Access denied", file permission errors Causes: Incorrect file permissions, ownership issues, insufficient privileges Solutions:

# Check file permissions
ls -la your_file.py

# Fix file permissions (Unix/Linux)
chmod 644 your_file.py
chmod +x your_script.py

# Fix ownership
chown your_user:your_group your_file.py

# Windows: Check file properties and security settings
# Right-click file → Properties → Security tab

# Check directory permissions
ls -la /path/to/directory/

# Fix directory permissions
chmod 755 /path/to/directory/

MCP Connection Issues

Symptoms: Connection failures, tool enumeration errors Causes: Incorrect configuration, network issues, service unavailable Solutions:

# Test MCP connection
aip mcps test-connection --from-file "mcp-config.json"

# Check MCP configuration
aip mcps get <MCP_ID>

# Verify external service is accessible (replace with your MCP base URL)
curl -v "$MCP_BASE_URL/health" || curl -v "$MCP_BASE_URL"

# If behind a proxy, ensure the AIP/MCP hosts are excluded:
export NO_PROXY="$NO_PROXY,your-aip-host,your-mcp-host"

Python SDK Issues

Import Errors

Symptoms: Module not found, import failures Causes: Wrong Python version, missing dependencies, installation issues Solutions:

# Check Python version (3.10+ required)
python --version

# Reinstall SDK
pip uninstall glaip-sdk
pip install glaip-sdk

# Install in development mode
pip install -e .

Client Initialization Errors

Symptoms: Client creation fails, configuration errors Causes: Missing environment variables, invalid configuration Solutions:

# Check environment variables (avoid sharing keys in logs)
import os
print(f"AIP_API_URL set? {bool(os.getenv('AIP_API_URL'))}")
print(f"AIP_API_KEY set? {bool(os.getenv('AIP_API_KEY'))}")

# For debugging, check key length/format without revealing content
key = os.getenv('AIP_API_KEY') or ""
if key:
    print(f"API key format: {key[:8]}...{key[-4:] if len(key) > 12 else '***'}")
else:
    print("API key not set")

# Initialize with explicit config
from glaip_sdk import Client
client = Client(
    api_url="https://your-api.com",
    api_key="your-key"
)

CLI Issues

Command Not Found

Symptoms: "aip: command not found" Causes: Installation failed, PATH issues, wrong installation method Solutions:

# Reinstall with pipx (recommended)
pipx install glaip-sdk

# Or install with pip
pip install --user glaip-sdk

# Add to PATH if needed
export PATH="$HOME/.local/bin:$PATH"

Invalid Command or Option

Symptoms: "No such command", "No such option" errors Causes: Using non-existent commands or options Solutions:

# Check available commands
aip --help

# Check available options for specific commands
aip agents --help
aip tools --help
aip mcps --help

# Use --view for output formatting (rich, plain, json, md)
aip agents list --view json
aip agents list --view plain

Shell Completion Issues

Symptoms: Tab completion not working, no suggestions Causes: Shell completion not currently implemented in the CLI Solutions:

# Note: Shell completion is not currently implemented in the CLI
# You can still use the CLI effectively without it

# Use --help for command discovery
aip --help
aip agents --help
aip tools --help

# Use --view json for structured output to make parsing easier
aip agents list --view json

Configuration Issues

Configuration Not Saved

Symptoms: Settings not persisting between sessions, configuration lost Causes: Wrong config file location, permission issues, invalid values Solutions:

# Check current configuration
aip config list

# Set configuration values
aip config set api_url "https://your-api.com"
aip config set api_key "your-api-key"

# Verify configuration was saved
aip config list

# Check config file location
# Default: ~/.aip/config.yaml

Invalid Configuration Values

Symptoms: "Invalid value" errors, configuration rejected Causes: Wrong format, invalid URLs, malformed values Solutions:

# Reset configuration to defaults
aip config reset

# Set values one by one to identify the problem
aip config set api_url "https://your-api.com"
aip config set api_key "your-api-key"

# Use interactive configuration
aip init

🚀 Performance Issues

Slow Response Times

Symptoms: Long delays, timeouts, slow execution Causes: Network latency, large requests, resource constraints Solutions:

Check network connectivity and latency
Optimize request size and complexity
Use appropriate timeouts
Consider local deployment for better performance

Memory Issues

Symptoms: High memory usage, out of memory errors Causes: Large file uploads, memory leaks, resource accumulation Solutions:

Monitor memory usage during operations
Clean up resources promptly
Use streaming for large files
Implement proper error handling and cleanup

Note: "Streaming" here refers to how agent output is delivered (SSE/logging). It doesn't change how files are uploaded. Use streaming to reduce output buffering; for large uploads, keep files smaller than the documented limits and upload only what's needed.

🆘 Getting Help

What to Include When Opening an Issue

Environment Details:
- Operating system and version
- Python version
- SDK version (pip show glaip-sdk)
- CLI version (aip --version)
Error Information:
- Full error message and traceback
- Steps to reproduce
- Expected vs. actual behavior
Configuration:
- API URL and key (redacted)
- Environment variables
- Configuration files (aip config list)
Logs and Debug Output:
- CLI output with --view json for structured debugging
- Network traces (if applicable)
- System logs

Support Channels

Documentation: Check this troubleshooting guide first
Examples: Review working examples in the guides
Community: Join discussions for help and tips
Issues: Report bugs via GitHub issues
Enterprise: Contact us for dedicated support

Quick Start - Get running quickly
Install & Configure - Setup instructions
Core Concepts - Understand the architecture
Upgrade Guides - Breaking changes and migrations

Most issues can be resolved by checking the Quick Fixes table above. If you're still having trouble, collect the diagnostic information and reach out for help!

PreviousTroubleshooting & FAQs

🚨 Quick Fixes (Symptom → Fix Table)

🔍 Collect Diagnostics

Enable Debug Mode

Check System Status

🔧 Common Issues

Connection Problems

401 Unauthorized

404 Not Found

Connection Refused

TLS/SSL Certificate Errors

Streaming Issues

Stream Hangs

Rich Output Issues

Output Formatting Issues

Resource Management

Rate Limiting Issues

Agent Not Found

Tool Execution Failed

Permission Issues

MCP Connection Issues

Python SDK Issues

Import Errors

Client Initialization Errors

CLI Issues

Command Not Found

Invalid Command or Option

Shell Completion Issues

Configuration Issues

Configuration Not Saved

Invalid Configuration Values

🚀 Performance Issues

Slow Response Times

Memory Issues

🆘 Getting Help

What to Include When Opening an Issue

Support Channels

📚 Related Documentation