Troubleshooting Guide

Common issues and solutions for KoreShield.

1. "Provider Error: 401 Unauthorized"

Symptoms: Requests fail with 500 error, logs show "Provider API error". Cause: Missing or incorrect API keys for the downstream LLM provider. Fix:

• Check .env file for OPENAI_API_KEY, etc.
• Verify keys are valid.
• Restart the server to reload environment variables.

2. "Connection Refused" (CLI/Client)

Symptoms: Client cannot connect to http://localhost:8000. Cause: The KoreShield proxy is not running or running on a different port. Fix:

• Run uvicorn src.koreshield.main:app --reload --port 8000
• Check if port 8000 is occupied (lsof -i :8000).

3. "Blocked by KoreShield" (False Positives)

Symptoms: Legitimate prompts are being blocked. Cause: Sensitivity settings are too high or a specific rule is too aggressive. Fix:

• Go to Dashboard > Configuration.
• Lower "Sensitivity" to "Low".
• Or, whitelist specific terms in the "Allowlist".

4. Dashboard Login Issues

Symptoms: Cannot log in to the admin dashboard. Cause: GitHub OAuth not configured or database connection for auth failed. Fix:

• Check GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET.
• Ensure BETTER_AUTH_SECRET is set.