docs/troubleshooting.md

AuroraAI Troubleshooting Guide

Common Issues & Fixes

1. Assistant Not Responding

Symptoms: Long delays or no output.

Possible Causes & Fixes:

• Network issue → Check VPN/firewall.
• Expired API key → Run aurora auth refresh.
• Large file uploads throttled → Compress or split files.

2. Incorrect or Irrelevant Answers

Symptoms: Hallucinations, outdated info.

Fixes:

• Re-index documentation: aurora connect ./docs --force.

Troubleshooting Connection Issues

Symptoms

• Failed API requests or timeouts
• Unable to connect to external services (GitHub, Jira, etc.)
• Network-related error messages

Common Causes and Solutions

Network Connectivity

• Check internet connection: Verify your network is stable and accessible
• Firewall settings: Ensure Aurora is allowed through your firewall
• Proxy configuration: If behind a corporate proxy, configure proxy settings in Aurora's config file

DNS Resolution

• Verify domain resolution: Test connectivity to API endpoints using ping or nslookup
• DNS cache: Clear system DNS cache if experiencing intermittent issues
• Alternative DNS: Try switching to public DNS servers (e.g., 8.8.8.8)

SSL/TLS Errors

• Certificate validation: Update system certificates or use --insecure flag for testing only
• Protocol version: Ensure TLS 1.2+ is supported on your system
• Corporate SSL inspection: Request certificate authority (CA) certificate from IT if applicable

Timeout Issues

• Increase timeout values: Use --timeout=60 flag to extend wait time
• Check service status: Verify third-party service availability at their status pages
• Reduce payload size: Break large requests into smaller batches

Debug Mode

Enable verbose logging to diagnose connection problems:

• Add explicit context to prompts.
• Enable strict retrieval with: --retrieval=strict.

3. Authentication Errors

Code	Meaning	Fix
401	Invalid token	Re-enter API key
403	Permission denied	Check role settings
429	Rate limit exceeded	Reduce request size or upgrade plan

4. Integration Sync Failures

Fixes:

• Validate GitHub/Jira tokens.
• Re-auth via: aurora integrate github --reset.
• Clear cache: aurora cache purge.

5. Advanced Connection Diagnostics

Network Layer Analysis

TCP/IP Stack Verification:

• Run netstat -an | grep ESTABLISHED to check active connections
• Monitor packet loss: ping -c 100 api.aurora.ai and analyze statistics
• Use traceroute api.aurora.ai to identify routing bottlenecks
• Check MTU settings: ping -M do -s 1472 api.aurora.ai to test fragmentation

Port Availability:

• Verify required ports are open: 443 (HTTPS), 80 (HTTP fallback)
• Test with telnet api.aurora.ai 443 or nc -zv api.aurora.ai 443
• Check for port conflicts: lsof -i :443 (Linux/macOS) or netstat -ano | findstr :443 (Windows)

Protocol-Level Debugging

HTTP/HTTPS Traffic Inspection:

• Capture traffic with tcpdump -i any -w aurora.pcap host api.aurora.ai
• Analyze with Wireshark to inspect TLS handshakes and HTTP headers
• Use curl -vvv https://api.aurora.ai/health for detailed handshake output
• Enable request/response logging: export AURORA_DEBUG_HTTP=1

TLS Handshake Failures:

• Check cipher suite compatibility: openssl s_client -connect api.aurora.ai:443 -tls1_2
• Verify certificate chain: openssl s_client -showcerts -connect api.aurora.ai:443
• Test SNI (Server Name Indication): openssl s_client -servername api.aurora.ai -connect api.aurora.ai:443
• Inspect client certificate requirements if mutual TLS is enabled

DNS Deep Dive

Resolution Path Analysis:

• Query authoritative nameservers: dig @8.8.8.8 api.aurora.ai +trace
• Check DNS response times: dig api.aurora.ai | grep "Query time"
• Verify DNSSEC validation: dig api.aurora.ai +dnssec
• Test DNS-over-HTTPS: Configure DoH provider in system settings

DNS Cache Management:

• Linux: sudo systemd-resolve --flush-caches or sudo service nscd restart
• macOS: sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder
• Windows: ipconfig /flushdns
• Verify /etc/hosts (Unix) or C:\Windows\System32\drivers\etc\hosts (Windows) for override entries

Proxy and VPN Troubleshooting

Proxy Configuration Validation:

• Check environment variables: echo $HTTP_PROXY $HTTPS_PROXY $NO_PROXY
• Test proxy authentication: curl -x http://proxy.corp.com:8080 --proxy-user user:pass https://api.aurora.ai
• Configure in Aurora config: aurora config set proxy.url http://proxy.corp.com:8080
• Bypass proxy for testing: export NO_PROXY=api.aurora.ai

VPN-Specific Issues:

• Check split-tunneling configuration
• Verify VPN MTU: ip link show and adjust if < 1500
• Test with VPN disabled to isolate issue
• Check for IPv6 leakage: curl -6 https://api.aurora.ai vs curl -4 https://api.aurora.ai

Application-Level Diagnostics

Aurora Internal Logs:

• Enable maximum verbosity: aurora --log-level=trace <command>
• Tail log file in real-time: tail -f ~/.aurora/logs/aurora.log
• Filter connection events: grep -i "connection\|socket\|timeout" ~/.aurora/logs/aurora.log
• Structured JSON logging: aurora --log-format=json <command> | jq '.level="error"'

Request/Response Inspection:

• Capture full HTTP exchange: AURORA_DUMP_REQUESTS=1 aurora <command>
• Measure round-trip time: time aurora api healthcheck
• Test with minimal request: aurora api raw --method GET --endpoint /v1/health
• Verify request headers: Check User-Agent, Authorization, Content-Type in debug output

System Resource Constraints

Connection Pool Exhaustion:

• Check open file descriptors: ulimit -n and increase if needed
• Monitor active sockets: lsof -p $(pgrep aurora) | grep TCP
• Review connection pool settings: aurora config get http.max_connections
• Adjust keep-alive timeout: aurora config set http.keepalive_timeout 30

Memory and CPU Impact:

• Profile resource usage: top -p $(pgrep aurora) or htop
• Check for memory leaks during long-running operations
• Monitor thread count: ps -eLf | grep aurora | wc -l
• Enable profiling: aurora --profile=cpu <command>

Enterprise Environment Considerations

Corporate Security Appliances:

• SSL/TLS Inspection: Export CA certificate and install system-wide
• Web Application Firewalls: Whitelist Aurora user-agent string
• DLP (Data Loss Prevention): Configure exceptions for Aurora traffic
• CASB (Cloud Access Security Broker): Add Aurora domains to allowlist

Authentication Mechanisms:

• NTLM proxy authentication: aurora config set proxy.auth ntlm
• Kerberos/SPNEGO: Ensure valid ticket with klist
• Client certificates: Specify with --client-cert=/path/to/cert.pem --client-key=/path/to/key.pem
• OAuth token refresh: aurora auth token --refresh

Advanced Debugging Techniques

Packet Capture and Analysis:

# Capture on specific interface
sudo tcpdump -i eth0 -s 0 -w aurora_debug.pcap 'host api.aurora.ai'

# Filter by port and decode HTTP
sudo tcpdump -i any -A 'tcp port 443 and host api.aurora.ai'

# Real-time monitoring with timestamps
sudo tcpdump -i any -tttt 'host api.aurora.ai'

SystemTap/eBPF Tracing (Linux):

• Trace system calls: strace -f -e trace=network aurora <command>
• Monitor DNS queries: sudo tcpdump -i any port 53
• Track connection states: Use ss -tan state established

Performance Profiling:

• Generate flame graph: aurora --profile=cpu --profile-output=profile.pb.gz <command>
• Analyze with pprof: go tool pprof -http=:8080 profile.pb.gz
• Network timing breakdown: Use browser DevTools Network tab for web UI

Configuration File Troubleshooting

Verify Configuration Syntax:

# Validate config file
aurora config validate

# Show effective configuration
aurora config show --resolved

# Reset to defaults
aurora config reset --confirm

# Override specific setting
aurora --config=/tmp/test.yaml <command>

Common Configuration Issues:

• Incorrect endpoint URLs: Verify api.base_url setting
• Timeout values too low: Increase http.timeout and http.read_timeout
• Retry logic disabled: Enable with http.retry.enabled=true
• Connection limits: Adjust http.max_connections_per_host

External Service Integration Testing

GitHub Connectivity:

# Test GitHub API access
curl -H "Authorization: token YOUR_TOKEN" https://api.github.com/user

# Verify webhook endpoint
curl -X POST https://api.aurora.ai/webhooks/github/test

# Check SSH access
ssh -T [email protected]

Jira Connectivity:

# Test Jira REST API
curl -u [email protected]:api_token https://your-domain.atlassian.net/rest/api/3/myself

# Verify webhook delivery
aurora integrate jira test-webhook --project KEY

Logging and Monitoring

Continuous Monitoring Setup:

• Configure log aggregation: Ship logs to ELK, Splunk, or Datadog
• Set up alerts for connection failures
• Monitor error rates: grep -c "connection refused\|timeout" aurora.log
• Track success rates over time

Metrics Collection:

• Enable Prometheus metrics: aurora serve --metrics-port=9090
• Export connection statistics: aurora metrics export --format=json
• Dashboard visualization: Import Aurora Grafana dashboard

Emergency Workarounds

Temporary Fixes:

• Use alternative endpoint: aurora --api-url=https://backup.aurora.ai
• Offline mode (if supported): aurora --offline <command>
• Fallback to local processing: aurora --no-remote <command>
• Manual API calls: Use curl with stored authentication token

Escalation Path:

1. Collect diagnostic bundle: aurora diagnostic collect --output=aurora-diag.zip
2. Include system information: aurora version --verbose
3. Attach relevant logs and packet captures
4. Submit to support with issue details