Troubleshooting
Common issues and solutions for KoreShield
Troubleshooting
Common issues and their solutions when using KoreShield.
Configuration Issues
Invalid Configuration File
Error: Configuration validation failed
Solution:
# Validate your config file
koreshield validate --config config.yaml
# Check for common issues:
# - Missing required fields
# - Invalid API key format
# - Incorrect indentation (YAML)
# - Invalid provider URLsProvider Connection Failed
Error: Failed to connect to LLM provider
Solutions:
# Check your provider configuration
providers:
openai:
api_key: "sk-..." # Ensure this is correct
base_url: "https://api.openai.com/v1" # Use correct endpoint# Test provider connectivity
koreshield test-connection --provider openaiSecurity Issues
False Positives
Problem: Legitimate requests being blocked
Solutions:
# Lower security sensitivity
security:
level: "low" # Try low, then medium
# Customize policies
policies:
prompt_injection_detection: "low"
on_suspicious: "warn" # Instead of "block"Missing Security Events
Problem: Security events not appearing in logs
Check:
logging:
level: "debug" # Temporarily enable debug logging
file: "/var/log/koreshield/security.log"Performance Issues
High Latency
Causes & Solutions:
-
Security scanning overhead:
security: level: "low" # Reduce for better performance -
Large request payloads:
policies: max_tokens_per_request: 2000 # Limit input size -
Resource constraints:
server: workers: 4 # Increase worker processes
Memory Usage
Problem: High memory consumption
Solutions:
# Limit concurrent requests
server:
max_concurrent_requests: 100
# Enable request cleanup
policies:
cleanup_temp_files: trueAPI Integration Issues
Authentication Failed
Error: 401 Unauthorized
Check:
- API key is correct and not expired
- Base URL points to KoreShield proxy
- Request headers are properly formatted
# Correct usage
client = openai.OpenAI(
api_key="sk-your-actual-openai-key",
base_url="http://localhost:8000/v1" # KoreShield URL
)Request Timeout
Problem: Requests timing out
Solutions:
# Increase timeout
server:
request_timeout: 300 # seconds
# Check provider status
koreshield test-connection --provider openaiDeployment Issues
Port Already in Use
Error: Port 8000 already in use
Solutions:
# Use different port
server:
port: 8001
# Find what's using the port
lsof -i :8000
kill -9 <PID>Docker Container Won't Start
Check:
# View container logs
docker logs koreshield
# Check configuration mount
docker run --rm -v $(pwd)/config.yaml:/app/config.yaml koreshield/koreshield validateLogging Issues
Logs Not Rotating
Problem: Log files growing too large
Solution:
logging:
max_size: "100MB"
retention: "30d"
compression: "gzip"Missing Log Entries
Check:
# Enable all logging
logging:
level: "debug"
console: true
file: "/var/log/koreshield/debug.log"Database Issues (Analytics)
TimescaleDB Connection Failed
Error: TIGER_DATA_URL environment variable is required
Note: Analytics features are optional. KoreShield works without TimescaleDB.
If you want analytics:
export TIGER_DATA_URL="postgres://user:pass@host:port/db"
koreshield startGetting Help
Debug Mode
Enable detailed logging for troubleshooting:
koreshield start --debugHealth Check
Check if KoreShield is running properly:
curl http://localhost:8000/healthSupport
- Check the GitHub Issues
- Review the Configuration Reference
- Enable debug logging and share relevant logs