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:
- Verify API key is correct and not expired
- Check API key format (should include
Bearer
prefix)
- 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:
- Check network connectivity
- Verify firewall settings
- 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
Problem: Tools failing to execute properly
Solutions:
- Check tool dependencies are installed
- Verify tool permissions
- 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:
- Increase container memory limits
- Optimize tool execution
- 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": {}}'
Causes:
- Network latency
- Resource constraints
- Inefficient tool implementation
Solutions:
- Optimize tool code
- Implement caching
- Use connection pooling
High Memory Usage
Causes:
- Memory leaks
- Large data processing
- Inefficient algorithms
Solutions:
- Profile memory usage
- Implement garbage collection
- 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
Problem: Cannot parse tool output
Solutions:
- Check output format
- Verify JSON structure
- 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:
- Install missing dependencies
- Update requirements file
- 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
When contacting support, include:
- Error messages and logs
- Environment details
- Steps to reproduce
- Configuration files (sanitized)
Responses are generated using AI and may contain mistakes.