​
Troubleshooting

This guide covers common issues and their solutions when working with Kubiya.

​
Common Issues

​
Authentication Errors

Problem: 401 Unauthorized errors when making API calls Solutions:
  1. Verify API key is correct and not expired
  2. Check API key format (should include Bearer prefix)
  3. Ensure proper environment variable configuration
# Check API key
echo $KUBIYA_API_KEY

# Test authentication
curl -H "Authorization: Bearer $KUBIYA_API_KEY" \
  https://api.kubiya.ai/v1/health

​
Connection Issues

Problem: Cannot connect to Kubiya services Solutions:
  1. Check network connectivity
  2. Verify firewall settings
  3. Ensure correct endpoint URLs
# Test connectivity
ping api.kubiya.ai

# Check DNS resolution
nslookup api.kubiya.ai

# Test specific port
telnet api.kubiya.ai 443

​
Tool Execution Failures

Problem: Tools failing to execute properly Solutions:
  1. Check tool dependencies are installed
  2. Verify tool permissions
  3. Review tool configuration
# Check tool status
kubiya tools list

# Test tool execution
kubiya tools test tool_name

# View tool logs
kubiya logs --tool tool_name

​
Memory/Resource Issues

Problem: Out of memory or resource exhaustion Solutions:
  1. Increase container memory limits
  2. Optimize tool execution
  3. Implement resource monitoring
# Docker Compose resource limits
services:
  kubiya-agent:
    deploy:
      resources:
        limits:
          memory: 4G
          cpus: '2'

​
Debugging

​
Enable Debug Logging

KUBIYA_LOG_LEVEL=DEBUG
KUBIYA_DEBUG=true

​
View Logs

# Docker logs
docker logs kubiya-agent -f

# Kubernetes logs
kubectl logs -f deployment/kubiya-agent -n kubiya

# Local logs
tail -f /var/log/kubiya/agent.log

​
Health Checks

# Check server health
curl http://localhost:8000/health

# Check tool discovery
curl http://localhost:8000/discovery

# Test tool execution
curl -X POST http://localhost:8000/execute \
  -H "Content-Type: application/json" \
  -d '{"tool": "test_tool", "parameters": {}}'

​
Performance Issues

​
Slow Tool Execution

Causes:
  • Network latency
  • Resource constraints
  • Inefficient tool implementation
Solutions:
  1. Optimize tool code
  2. Implement caching
  3. Use connection pooling

​
High Memory Usage

Causes:
  • Memory leaks
  • Large data processing
  • Inefficient algorithms
Solutions:
  1. Profile memory usage
  2. Implement garbage collection
  3. Use streaming for large data

​
Network Issues

​
SSL/TLS Errors

# Check SSL certificate
openssl s_client -connect api.kubiya.ai:443

# Verify certificate chain
curl -v https://api.kubiya.ai/v1/health

​
Proxy Configuration

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

# No proxy for local services
NO_PROXY=localhost,127.0.0.1,*.local

​
Data Issues

​
Tool Output Parsing

Problem: Cannot parse tool output Solutions:
  1. Check output format
  2. Verify JSON structure
  3. Handle edge cases
import json

try:
    result = json.loads(tool_output)
except json.JSONDecodeError as e:
    print(f"JSON parsing error: {e}")
    # Handle non-JSON output

​
Missing Dependencies

Problem: Required packages not found Solutions:
  1. Install missing dependencies
  2. Update requirements file
  3. Use Docker for consistent environment
# Install dependencies
pip install -r requirements.txt

# Check installed packages
pip list

# Update packages
pip install --upgrade package_name

​
Configuration Issues

​
Environment Variables

# Check all Kubiya environment variables
env | grep KUBIYA

# Verify configuration
kubiya config show

# Test configuration
kubiya config test

​
File Permissions

# Fix file permissions
chmod 755 /path/to/kubiya/files
chown kubiya:kubiya /path/to/kubiya/files

# Check permissions
ls -la /path/to/kubiya/files

​
Getting Help

​
Log Collection

# Collect system logs
kubiya logs --collect

# Generate debug report
kubiya debug --report

# Export configuration
kubiya config export > config.json

​
Support Information

When contacting support, include:
  1. Error messages and logs
  2. Environment details
  3. Steps to reproduce
  4. Configuration files (sanitized)