Troubleshooting Guide

This guide provides solutions to common issues encountered when using AI Security Gateway. Issues are organized by component and severity.

Quick Diagnostics

Health Check Commands

Before diving into specific issues, run these commands to check system health:

bash

# Check if server is running
curl http://localhost:8080/api/v1/health

# Expected response
{
  "status": "ok",
  "version": "2.1",
  "timestamp": "2025-11-11T..."
}

# Check server logs
tail -f logs/unified-admin.log

# View all proxies
curl http://localhost:8080/api/v1/proxies/

# Check database
ls -lh data/security.db

Enable Debug Logging

bash

# Set environment variable
export LOG_LEVEL=debug

# Restart server
./build/unified-admin

# Or with Docker
docker-compose down
docker-compose up -d

# View logs
docker-compose logs -f unified-admin

Server Issues

Issue: Server Fails to Start

Symptoms:

unified-admin command not found
Permission denied errors
Server crashes on startup
Port already in use errors

Solutions:

Verify Installation:

bash

# Check if binary exists
ls -la ./build/unified-admin

# Check permissions
chmod +x ./build/unified-admin

# Verify Go installation (for building from source)
go version

Check Port Availability:

bash

# Check if port 8080 is in use
lsof -i :8080
# or
netstat -tuln | grep 8080

# Kill process using port
kill -9 $(lsof -t -i:8080)

# Or use different port
export SERVER_PORT=8081
./build/unified-admin

Check Environment Variables:

bash

# Verify required variables are set (if using OAuth)
echo $JWT_SECRET
echo $ENCRYPTION_KEY

# Generate if missing
export JWT_SECRET=$(openssl rand -base64 32)
export ENCRYPTION_KEY=$(openssl rand -base64 32 | cut -c1-32)

Database Issues:

bash

# Check data directory exists
mkdir -p data
chmod 755 data

# Remove corrupted database (WARNING: loses data)
rm data/security.db
# Server will recreate on next start

Issue: Missing Environment Variables

Symptoms:

"JWT_SECRET not set" error
"ENCRYPTION_KEY not set" error
OAuth features not working

Solutions:

Create .env File:

bash

# Copy example
cp .env.example .env

# Generate secrets
cat > .env <<EOF
JWT_SECRET=$(openssl rand -base64 32)
ENCRYPTION_KEY=$(openssl rand -base64 32 | cut -c1-32)
DATABASE_PATH=./data/security.db
SERVER_PORT=8080
EOF

Verify Variables Are Loaded:

bash

# Check server logs for "Loaded environment variables"
./build/unified-admin 2>&1 | grep -i environment

Issue: Database Connection Errors

Symptoms:

"unable to open database file" error
"database is locked" error
Migration failures

Solutions:

Check Database Path:

bash

# Ensure directory exists
mkdir -p data
chmod 755 data

# Check database file permissions
ls -lh data/security.db
chmod 644 data/security.db

Database Locked:

bash

# Stop all instances
pkill unified-admin

# Wait a moment, then restart
./build/unified-admin

Reset Database (WARNING: loses all data):

bash

# Backup first
cp data/security.db data/security.db.backup

# Remove database
rm data/security.db

# Restart server (will recreate)
./build/unified-admin

Proxy Issues

Issue: General Proxy Won't Start

Symptoms:

Proxy creation succeeds but won't start
"Failed to start proxy" error
Proxy shows as "stopped" status

Solutions:

Check Port Availability:

bash

# Check if port is already in use
lsof -i :8081

# Use different port
curl -X PUT http://localhost:8080/api/v1/proxies/1 \
  -H "Content-Type: application/json" \
  -d '{"port": 8082}'

Check Target Connectivity:

bash

# Test target server is reachable
curl -I http://target-server:3000

# Check DNS resolution
nslookup target-server

# Test with telnet
telnet target-server 3000

View Proxy Logs:

bash

# Get detailed error information
curl http://localhost:8080/api/v1/proxies/1/logs

# Check server logs
tail -f logs/unified-admin.log | grep "proxy"

Verify Security Policies Exist:

bash

# Check policy files
ls -la policies/

# Validate JSON
jq '.' policies/critical-security.json

Issue: Proxy Connection Failures

Symptoms:

Cannot connect to target server through proxy
Connection timeouts
TLS/SSL errors
"502 Bad Gateway" errors

Solutions:

Network Connectivity:

bash

# Test direct connection to target
curl -v http://target-server:3000/health

# Check firewall rules
sudo iptables -L

# Test from proxy port
curl -v http://localhost:8081/health

TLS/SSL Issues:

bash

# Test TLS connection to target
openssl s_client -connect target-server:443

# Check certificate validity
echo | openssl s_client -connect target-server:443 2>/dev/null | openssl x509 -noout -dates

Check Proxy Configuration:

bash

# Get proxy config
curl http://localhost:8080/api/v1/proxies/1

# Verify target URL is correct
# Check transport type matches (http, websocket, sse)

Issue: WebSocket Proxy Problems

Symptoms:

WebSocket upgrade failures
Message corruption
Connection drops
"Failed to upgrade connection" errors

Solutions:

Verify Transport Setting:

bash

# Check proxy transport is set to "websocket"
curl http://localhost:8080/api/v1/proxies/1 | jq '.transport'

# Update if needed
curl -X PUT http://localhost:8080/api/v1/proxies/1 \
  -H "Content-Type: application/json" \
  -d '{"transport": "websocket"}'

Test WebSocket Connection:

bash

# Install wscat if needed
npm install -g wscat

# Test WebSocket connection
wscat -c ws://localhost:8081

Check Upgrade Headers:

bash

# Verify upgrade headers are present
curl -i -N \
  -H "Connection: Upgrade" \
  -H "Upgrade: websocket" \
  -H "Sec-WebSocket-Key: test" \
  -H "Sec-WebSocket-Version: 13" \
  http://localhost:8081

Issue: High Proxy Latency

Symptoms:

Slow response times
Request timeouts
Performance degradation

Solutions:

Check Target Server Performance:

bash

# Measure direct target latency
time curl http://target-server:3000/health

# Measure proxy latency
time curl http://localhost:8081/health

# Compare difference

Review Proxy Statistics:

bash

# Get proxy stats
curl http://localhost:8080/api/v1/proxies/1/stats

# Look for:
# - High request count
# - Long average duration
# - Many blocked requests

Optimize Security Policies:

bash

# Use lighter policy for high-performance needs
curl -X PUT http://localhost:8080/api/v1/proxies/1/policies \
  -H "Content-Type: application/json" \
  -d '{"policies": ["standard-security"]}'  # Instead of mcp-advanced-security

Check System Resources:

bash

# Monitor server resources
top -p $(pgrep unified-admin)

# Check memory usage
ps aux | grep unified-admin

OAuth & Authentication Issues

Symptoms:

"Provider not configured" error
Redirect loops
"Invalid credentials" error
401 Unauthorized responses

Solutions:

Check OAuth Provider Configuration:

bash

# Verify provider is configured
curl http://localhost:8080/api/v1/auth/oauth/providers

# Expected response (if GitHub configured)
{
  "success": true,
  "data": {
    "providers": ["github"]
  }
}

Verify Environment Variables:

bash

# Check OAuth credentials are set
echo $OAUTH_GITHUB_CLIENT_ID
echo $OAUTH_GITHUB_CLIENT_SECRET

# Check JWT secrets
echo $JWT_SECRET
echo $ENCRYPTION_KEY

# All should return values

Check Callback URL:

bash

# Callback URL must match what's configured in OAuth provider
# Default: http://localhost:8080/api/v1/auth/oauth/callback/{provider}

# For production, update in OAuth provider settings:
# https://yourdomain.com/api/v1/auth/oauth/callback/github

Check Provider Settings:
- GitHub: Go to Settings → Developer settings → OAuth Apps
- Google: Go to Google Cloud Console → Credentials
- Microsoft: Go to Azure Portal → App registrations
- Verify client ID and secret match environment variables

Issue: Session Expired or Invalid

Symptoms:

Frequent logouts
"Session expired" errors
"Invalid session token" errors

Solutions:

Check Session Duration:

yaml

# In configs/config.yaml
oauth:
  session_duration: 24h  # Default is 24 hours

Verify Encryption Key:

bash

# ENCRYPTION_KEY must be exactly 32 characters
echo -n $ENCRYPTION_KEY | wc -c
# Should output: 32

# Regenerate if needed
export ENCRYPTION_KEY=$(openssl rand -base64 32 | cut -c1-32)

Clear Browser Cookies:
- Browser may have stale cookies
- Clear cookies for localhost or your domain
- Try incognito/private browsing mode

Issue: User Access Denied to Proxy

Symptoms:

"Access denied" when trying to use proxy
User can log in but can't access proxies
403 Forbidden errors

Solutions:

Check User Group Assignment:

bash

# List user's groups
curl http://localhost:8080/api/v1/auth/users/me

# Check group has access to proxy
curl http://localhost:8080/api/v1/auth/groups/{group_id}/proxies

Assign User to Group:

bash

# Via web interface: Settings → User Management

# Via API:
curl -X POST http://localhost:8080/api/v1/auth/groups/{group_id}/users/{user_id}

Grant Group Access to Proxy:

bash

# Via web interface: Settings → Access Control

# Via API:
curl -X POST http://localhost:8080/api/v1/auth/groups/{group_id}/proxies \
  -H "Content-Type: application/json" \
  -d '{"proxy_id": 1}'

Frontend & Web Interface Issues

Issue: Cannot Access Web Interface

Symptoms:

Blank page at http://localhost:8080
404 Not Found errors
Static assets not loading

Solutions:

Check Server is Running:

bash

# Test API endpoint
curl http://localhost:8080/api/v1/health

# If API works but web doesn't, frontend may not be built

Build Frontend:

bash

cd frontend
npm install
npm run build
cd ..

# Restart server
./build/unified-admin

Check Frontend Build Location:

bash

# Verify dist directory exists
ls -la frontend/dist/

# Server looks for frontend in ./frontend/dist/

Issue: CORS Errors in Browser

Symptoms:

"blocked by CORS policy" errors in console
API requests fail from frontend
Network tab shows CORS errors

Solutions:

Check CORS Configuration:

bash

# For development (default)
export ENVIRONMENT=development
# Automatically allows localhost and private IPs

# For production
export ENVIRONMENT=production
export ALLOWED_ORIGINS=https://yourdomain.com,https://admin.yourdomain.com

Verify Origin Header:

bash

# Test CORS with curl
curl -v -H "Origin: http://localhost:3000" \
  http://localhost:8080/api/v1/health

# Should include Access-Control-Allow-Origin header

Check Server Logs:

bash

# Look for "CORS: Rejected origin" messages
tail -f logs/unified-admin.log | grep CORS

Issue: Frontend Can't Connect to Backend

Symptoms:

"Network Error" in frontend
API calls timeout
Connection refused errors

Solutions:

Check API Base URL:

bash

# In frontend/.env or frontend/.env.local
VITE_API_BASE_URL=http://localhost:8080

# Rebuild frontend after changing
cd frontend
npm run build

Clear Vite Cache:

bash

cd frontend
rm -rf node_modules/.vite
npm run dev

Check Backend is Accessible:

bash

# From frontend perspective
curl http://localhost:8080/api/v1/health

Database & Data Issues

Issue: Database Migration Failures

Symptoms:

"migration failed" errors on startup
"table already exists" errors
"column not found" errors

Solutions:

Check Database Version:

bash

# View database schema
sqlite3 data/security.db ".schema"

Backup and Reset (loses data):

bash

# Backup database
cp data/security.db data/security.db.$(date +%Y%m%d)

# Remove database
rm data/security.db

# Restart server (auto-migrates)
./build/unified-admin

Manual Migration (advanced):

bash

# Connect to database
sqlite3 data/security.db

# Run SQL commands to fix schema
# (See migration files in internal/database/migrations/)

Issue: Lost Data After Restart

Symptoms:

Proxies disappear after restart
Users need to re-authenticate
Configuration resets

Solutions:

Check Database Persistence:

bash

# Verify DATABASE_PATH is set
echo $DATABASE_PATH

# Check file exists
ls -lh data/security.db

# Verify not using :memory: database
grep "database:" configs/config.yaml

Check File Permissions:

bash

# Ensure server can write
chmod 644 data/security.db
chmod 755 data/

Docker Volume Mounting:

bash

# Ensure volume is mounted correctly
docker-compose down

# Check docker-compose.yml
volumes:
  - ./data:/app/data  # Must be present

docker-compose up -d

Alert & Monitoring Issues

Issue: No Alerts Being Generated

Symptoms:

Security violations not creating alerts
Alert dashboard shows no data
Policies appear to not be working

Solutions:

Check Proxy is Running:

bash

# Verify proxy status
curl http://localhost:8080/api/v1/proxies/1/status

# Should show "running": true

Verify Policies Are Assigned:

bash

# Check proxy has policies
curl http://localhost:8080/api/v1/proxies/1 | jq '.policies'

# Should list policy names like ["critical-security"]

Send Test Request:

bash

# Send request that should trigger alert
curl -X POST http://localhost:8081/tools/call \
  -H "Content-Type: application/json" \
  -d '{"name":"exec","arguments":{"command":"rm -rf /"}}'

# Check alerts
curl http://localhost:8080/api/v1/system/alerts

Check Policy Files:

bash

# Validate policy exists and is valid JSON
jq '.' policies/critical-security.json

# Check for syntax errors

Issue: Too Many False Positive Alerts

Symptoms:

Legitimate traffic flagged as malicious
Alert fatigue
High number of low-severity alerts

Solutions:

Tune Security Policies:

bash

# Use lighter policy
curl -X PUT http://localhost:8080/api/v1/proxies/1/policies \
  -H "Content-Type: application/json" \
  -d '{"policies": ["standard-security"]}'

# Instead of "mcp-advanced-security" or "critical-security"

Create Custom Policy:

bash

# Copy existing policy
cp policies/standard-security.json policies/custom-policy.json

# Edit to remove problematic rules
vi policies/custom-policy.json

# Assign to proxy
curl -X PUT http://localhost:8080/api/v1/proxies/1/policies \
  -H "Content-Type: application/json" \
  -d '{"policies": ["custom-policy"]}'

Filter Alerts:

bash

# View only high-severity alerts
curl "http://localhost:8080/api/v1/system/alerts?severity=High,Critical"

# Filter by time
curl "http://localhost:8080/api/v1/system/alerts?time_range=1h"

Integration Issues

Issue: Slack Notifications Not Working

Symptoms:

Alerts generated but no Slack messages
"Failed to send Slack notification" in logs
Webhook errors

Solutions:

Verify Webhook URL:

bash

# Check webhook is set
echo $SLACK_WEBHOOK_URL

# Test webhook manually
curl -X POST $SLACK_WEBHOOK_URL \
  -H "Content-Type: application/json" \
  -d '{"text":"Test message"}'

Check Settings:

bash

# Via web interface: Settings → Integrations

# Via API:
curl http://localhost:8080/api/v1/system/settings | jq '.slack'

# Enable if disabled:
curl -X PUT http://localhost:8080/api/v1/system/settings \
  -H "Content-Type: application/json" \
  -d '{"slack_enabled":true,"slack_webhook":"https://hooks.slack.com/..."}'

Check Severity Filter:

yaml

# In configs/config.yaml
integration:
  slack:
    severity_filter: ["Critical", "High"]  # Only these severities sent

Issue: SIEM Integration Not Sending Alerts

Symptoms:

SIEM not receiving alerts
Connection timeout to SIEM endpoint
Authentication failures

Solutions:

Test SIEM Endpoint:

bash

# Test connectivity
curl -v $SIEM_ENDPOINT

# Test with authentication
curl -v -H "Authorization: Bearer $SIEM_API_KEY" $SIEM_ENDPOINT

Check Configuration:

bash

# Via web interface: Settings → Integrations → SIEM

# Via API:
curl http://localhost:8080/api/v1/system/settings | jq '.siem'

Check Logs:

bash

# Look for SIEM-related errors
tail -f logs/unified-admin.log | grep -i siem

General Performance Issues

Issue: General High Memory Usage

Symptoms:

Server using excessive memory
Out of memory errors
Slow performance

Solutions:

Check Current Usage:

bash

# Monitor memory
ps aux | grep unified-admin
top -p $(pgrep unified-admin)

Check Database Size:

bash

# Large database can cause high memory usage
ls -lh data/security.db

# Clean old data
curl -X DELETE "http://localhost:8080/api/v1/system/alerts?older_than=30d"

Limit Alert Retention:

yaml

# In configs/config.yaml
audit:
  retention_days: 30  # Clean old audit logs

Restart Server Periodically:

bash

# Set up cron job or systemd timer
# to restart weekly

Issue: High CPU Usage

Symptoms:

CPU constantly high
Server slow to respond
High system load

Solutions:

Check Active Proxies:

bash

# List running proxies
curl http://localhost:8080/api/v1/proxies/ | jq '.[] | select(.status=="running")'

# Stop unused proxies
curl -X POST http://localhost:8080/api/v1/proxies/{id}/stop

Simplify Security Policies:

bash

# Complex regex patterns can cause high CPU
# Use simpler policies for high-traffic proxies

Check for Policy Loops:

bash

# Review logs for repeated pattern matching
tail -f logs/unified-admin.log | grep "pattern"

Docker Issues

Issue: Docker Container Won't Start

Symptoms:

Container exits immediately
"Error response from daemon"
Health check failures

Solutions:

Check Container Logs:

bash

# View logs
docker logs unified-admin

# Or with docker-compose
docker-compose logs unified-admin

Check Environment Variables:

bash

# Verify .env file exists
cat .env

# Check variables are loaded
docker-compose config | grep JWT_SECRET

Check Volume Mounts:

bash

# Verify data directory exists
mkdir -p data
chmod 755 data

# Restart
docker-compose down
docker-compose up -d

Issue: Docker Can't Connect to Host Services

Symptoms:

Proxy can't reach target on localhost
"connection refused" to host.docker.internal
Network errors

Solutions:

Use host.docker.internal:

bash

# Instead of localhost, use:
# target: "http://host.docker.internal:3000"

# Create proxy with correct target
curl -X POST http://localhost:8080/api/v1/proxies/ \
  -d '{"target":"http://host.docker.internal:3000",...}'

Use Host Network Mode:

yaml

# In docker-compose.yml
services:
  unified-admin:
    network_mode: "host"

Check Firewall:

bash

# Ensure Docker can access host ports
sudo iptables -L

Common Error Messages

ENCRYPTION_KEY Must Be Exactly 32 Characters

Solution:

bash

export ENCRYPTION_KEY=$(openssl rand -base64 32 | cut -c1-32)

JWT_SECRET Not Set or Too Short

Solution:

bash

export JWT_SECRET=$(openssl rand -base64 32)

Failed to Connect to Database

Solution:

bash

mkdir -p data
chmod 755 data
export DATABASE_PATH=./data/security.db

Port Already in Use

Solution:

bash

# Kill process using port
kill -9 $(lsof -t -i:8080)

# Or use different port
export SERVER_PORT=8081

Policy File Not Found

Solution:

bash

# Check policies directory
ls -la policies/

# Verify policy name matches filename
# "critical-security" requires policies/critical-security.json

Getting Troubleshooting Help

If issues persist:

Enable Debug Logging:

bash

export LOG_LEVEL=debug
./build/unified-admin 2>&1 | tee debug.log

Collect Diagnostic Information:

bash

# System info
uname -a
go version
node --version

# Server status
curl http://localhost:8080/api/v1/health

# Database status
ls -lh data/

# Environment (redact secrets!)
env | grep -E "(SERVER|DATABASE|OAUTH)" | sed 's/=.*/=***/'

Check Documentation:
Report Issues:
- GitHub Issues: https://github.com/syphon1c/ai-security-gateway/issues
- Include debug logs, system info, and steps to reproduce

Symptoms:

Slow response times
Connection timeouts
Performance degradation

Solutions:

Performance Tuning:

yaml

proxy:
  performance:
    bufferSize: 8192
    maxConnections: 1000
    keepAlive: true

Resource Monitoring:

bash

# Monitor unified-admin process performance
top -p $(pgrep unified-admin)
iotop -p $(pgrep unified-admin)

# Or view metrics via web UI: http://localhost:8080 → System → Metrics
# Or via API:
curl http://localhost:8080/api/v1/system/metrics \
  -H "Authorization: Bearer YOUR_TOKEN"

Network Optimisation:
- Use local network interfaces
- Optimise TCP settings
- Consider hardware acceleration

Issue: Proxy Status Synchronisation Problems

Symptoms:

Web UI shows proxy as "running" but stop operation fails with "proxy is not running"
Inconsistent proxy status after service restart
Database status doesn't match actual running state

Root Cause: This issue occurs when the AI Security Gateway service is killed (e.g., pkill unified-admin or system restart) while proxies are running. The in-memory proxy state is lost, but the database retains stale "running" status.

Solutions:

Automatic Fix (v2026.x.x-beta and later):

bash

# The service now automatically cleans up stale status on startup
# Restart the unified-admin service
systemctl restart unified-admin
# Or if running manually:
./build/unified-admin
# Wait 2-3 seconds for cleanup to complete

Manual Status Verification:

bash

# Check actual proxy status
curl -s "http://localhost:8080/api/v1/proxies/status" | jq

# Verify status matches reality
netstat -tuln | grep 8040  # Check if proxy port is actually bound

Force Status Reset (if automatic cleanup fails):

bash

# Stop all proxies via API (clears in-memory state)
curl -X POST "http://localhost:8080/api/v1/proxies/1/stop"
curl -X POST "http://localhost:8080/api/v1/proxies/2/stop"

# Restart desired proxies
curl -X POST "http://localhost:8080/api/v1/proxies/1/start"

Prevention:

Use auto_start: true for critical proxies that should restart automatically
Use proper shutdown: systemctl stop unified-admin or graceful shutdown via API instead of kill -9 when possible
Monitor proxy status after service restarts

Technical Details:

The service now implements cleanupStaleProxyStatus() that runs 2 seconds after startup
Status verification compares database records with in-memory runningProxies map
Auto-start proxies are started correctly and maintain accurate status

Configuration Issues

Issue: Configuration File Problems

Symptoms:

Configuration not loaded
Invalid configuration errors
Default values not applied

Solutions:

File Location:

bash

# Check default locations
ls ./configs/config.yaml
# Configuration is managed via environment variables or database
# Check environment variables:
env | grep -E "(JWT_SECRET|ENCRYPTION_KEY|OAUTH_)"
# Configuration is managed via environment variables or database
# Check environment variables:
env | grep -E "(JWT_SECRET|ENCRYPTION_KEY|OAUTH_)"

YAML Syntax Validation:

bash

# Validate YAML syntax
python -c "import yaml; yaml.safe_load(open('./configs/config.yaml'))"

# Check indentation
cat -A ./configs/config.yaml

Configuration Override:

bash

# Specify config file explicitly
# Configuration is managed via environment variables
# Set environment variables before starting unified-admin:
export JWT_SECRET="your-secret"
export ENCRYPTION_KEY="your-key"
./build/unified-admin

# Then use vulnerability scan via web UI or API

# Use environment variables
export MCP_CONFIG_FILE=./configs/config.yaml

Issue: Integration Configuration

Symptoms:

SIEM integration failures
Webhook delivery issues
Authentication problems

Solutions:

Endpoint Testing:

bash

# Test SIEM endpoint
curl -X POST https://siem-endpoint.com/api/alerts \
     -H "Content-Type: application/json" \
     -d '{"test": "message"}'

# Verify webhook URL
curl -X POST https://hooks.slack.com/services/... \
     -d '{"text": "Test message"}'

Authentication Verification:

yaml

integration:
  siem:
    endpoint: "https://siem.company.com/api"
    apiKey: "your-api-key"
    timeout: 30

Network Access:
- Check firewall rules for outbound connections
- Verify DNS resolution for integration endpoints
- Test connectivity from scanning environment

Report Generation Issues

Issue: Report Generation Failures

Symptoms:

Empty report files
Format conversion errors
File permission issues

Solutions:

Directory Permissions:

bash

# Check output directory
ls -la ./reports/

# Create directory if missing
mkdir -p ./reports/
chmod 755 ./reports/

Format-Specific Issues:

bash

# Generate reports in different formats via web UI or API
# Web UI: http://localhost:8080 → MCP Security → Vulnerability Scan → Download Report
# JSON format via API:
curl http://localhost:8080/api/v1/mcp/scan/SCAN_ID/result \
  -H "Authorization: Bearer YOUR_TOKEN"

# PDF format via API:
curl http://localhost:8080/api/v1/mcp/scan/SCAN_ID/pdf \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -o report.pdf

Template Issues:

bash

# Check template files
ls -la ./templates/

# Validate template syntax
go run -c 'package main; import "text/template"; template.Must(template.ParseFiles("./templates/report.html"))'

Issue: PDF Generation Problems

Symptoms:

PDF files corrupted or empty
Font rendering issues
Layout problems

Solutions:

Pure Go Implementation:

bash

# No external dependencies required
# Download PDF report via API:
curl http://localhost:8080/api/v1/mcp/scan/SCAN_ID/pdf \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -o report.pdf

Alternative PDF Generation:

bash

# Generate HTML report via web UI: http://localhost:8080 → MCP Security → Vulnerability Scan → [Scan] → View Report
# Then use browser print-to-PDF functionality

Font Configuration (if text rendering issues):

bash

# Check available fonts (Linux)
fc-list

# Install additional fonts if needed (Linux)
sudo apt-get install fonts-liberation

Performance Optimisation

Memory Usage Optimisation

bash

# Monitor memory usage
ps aux | grep mcpscan

# Increase Go garbage collection
export GOGC=50

# Limit memory usage
ulimit -v 4194304  # 4GB virtual memory limit

CPU Usage Optimisation

bash

# Limit CPU usage
cpulimit -l 50 -p $(pgrep unified-admin)

# Use multiple cores efficiently
export GOMAXPROCS=4

Disk I/O Optimisation

bash

# Use SSD storage for temporary files
export TMPDIR=/path/to/ssd/tmp

# Monitor disk usage
iotop -p $(pgrep unified-admin)

General Debugging Tips

Enable Verbose Logging

bash

# Maximum verbosity
# Enable debug logging via environment variable:
LOG_LEVEL=debug ./build/unified-admin

# Then use vulnerability scan via web UI or API

# Log to file
# Run vulnerability scan and capture logs:
curl -X POST http://localhost:8080/api/v1/mcp/scan \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"proxy_id": PROXY_ID, "policy": "critical-security"}' 2>&1 | tee scan.log

Network Debugging

bash

# Capture network traffic
sudo tcpdump -i any -w mcpscan.pcap host target-server.com

# Monitor connections
netstat -an | grep mcpscan

Memory Debugging

bash

# Check for memory leaks
# Use valgrind on unified-admin (if needed for debugging):
valgrind --tool=memcheck ./build/unified-admin
# Then use vulnerability scan via web UI or API

# Go memory profiling
go tool pprof http://localhost:6060/debug/pprof/heap

Support and Diagnostics

Log Information to Collect

When reporting issues, include:

Version Information:

bash

# Check version via API:
curl http://localhost:8080/api/v1/system/version \
  -H "Authorization: Bearer YOUR_TOKEN"

# Or view in web UI: http://localhost:8080 → System → About
go version
uname -a

Configuration:

bash

# Sanitised configuration (remove secrets)
cat ./configs/config.yaml | sed 's/apiKey:.*/apiKey: [REDACTED]/'

Error Messages:

bash

# Full error output
# Run vulnerability scan with verbose logging:
# Enable debug logging first:
export LOG_LEVEL=debug
./build/unified-admin

# Then run scan via web UI or API:
curl -X POST http://localhost:8080/api/v1/mcp/scan \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"proxy_id": PROXY_ID, "policy": "critical-security"}' 2>&1

System Information:
bash
```
# Resource usage
free -h
df -h
top -n 1
```

Troubleshooting Support Channels

GitHub Issues: Report bugs and feature requests
Documentation: Check latest documentation updates
Community Forum: Discuss best practices and configurations

General Emergency Procedures

For critical security incidents:

Stop affected services immediately
Preserve logs and evidence
Contact security team
Follow incident response procedures
Update security policies based on lessons learned

Installation Guide - Setup and deployment
Configuration Reference - Configuration options
Admin Quick Start Guide - Quick setup
OAuth Setup Guide - Authentication setup
Architecture Overview - System architecture
API Examples - API usage examples

Troubleshooting Guide ​

Quick Diagnostics ​

Health Check Commands ​

Enable Debug Logging ​

Server Issues ​

Issue: Server Fails to Start ​

Issue: Missing Environment Variables ​

Issue: Database Connection Errors ​

Proxy Issues ​

Issue: General Proxy Won't Start ​

Issue: Proxy Connection Failures ​

Issue: WebSocket Proxy Problems ​

Issue: High Proxy Latency ​

OAuth & Authentication Issues ​

Issue: General OAuth Login Fails ​

Issue: Session Expired or Invalid ​

Issue: User Access Denied to Proxy ​

Frontend & Web Interface Issues ​

Issue: Cannot Access Web Interface ​

Issue: CORS Errors in Browser ​

Issue: Frontend Can't Connect to Backend ​

Database & Data Issues ​

Issue: Database Migration Failures ​

Issue: Lost Data After Restart ​

Alert & Monitoring Issues ​

Issue: No Alerts Being Generated ​

Issue: Too Many False Positive Alerts ​

Integration Issues ​

Issue: Slack Notifications Not Working ​

Issue: SIEM Integration Not Sending Alerts ​

General Performance Issues ​

Issue: General High Memory Usage ​

Issue: High CPU Usage ​

Docker Issues ​

Issue: Docker Container Won't Start ​

Issue: Docker Can't Connect to Host Services ​

Common Error Messages ​

ENCRYPTION_KEY Must Be Exactly 32 Characters ​

JWT_SECRET Not Set or Too Short ​

Failed to Connect to Database ​

Port Already in Use ​

Policy File Not Found ​

Getting Troubleshooting Help ​

Issue: Proxy Status Synchronisation Problems ​

Configuration Issues ​

Issue: Configuration File Problems ​

Issue: Integration Configuration ​

Report Generation Issues ​

Issue: Report Generation Failures ​

Issue: PDF Generation Problems ​

Performance Optimisation ​

Memory Usage Optimisation ​

CPU Usage Optimisation ​

Disk I/O Optimisation ​

General Debugging Tips ​

Enable Verbose Logging ​

Network Debugging ​

Memory Debugging ​

Support and Diagnostics ​

Log Information to Collect ​

Troubleshooting Support Channels ​

General Emergency Procedures ​

Troubleshooting Related Documentation ​

Troubleshooting Guide

Quick Diagnostics

Health Check Commands

Enable Debug Logging

Server Issues

Issue: Server Fails to Start

Issue: Missing Environment Variables

Issue: Database Connection Errors

Proxy Issues

Issue: General Proxy Won't Start

Issue: Proxy Connection Failures

Issue: WebSocket Proxy Problems

Issue: High Proxy Latency

OAuth & Authentication Issues

Issue: General OAuth Login Fails

Issue: Session Expired or Invalid

Issue: User Access Denied to Proxy

Frontend & Web Interface Issues

Issue: Cannot Access Web Interface

Issue: CORS Errors in Browser

Issue: Frontend Can't Connect to Backend

Database & Data Issues

Issue: Database Migration Failures

Issue: Lost Data After Restart

Alert & Monitoring Issues

Issue: No Alerts Being Generated

Issue: Too Many False Positive Alerts

Integration Issues

Issue: Slack Notifications Not Working

Issue: SIEM Integration Not Sending Alerts

General Performance Issues

Issue: General High Memory Usage

Issue: High CPU Usage

Docker Issues

Issue: Docker Container Won't Start

Issue: Docker Can't Connect to Host Services

Common Error Messages

ENCRYPTION_KEY Must Be Exactly 32 Characters

JWT_SECRET Not Set or Too Short

Failed to Connect to Database

Port Already in Use

Policy File Not Found

Getting Troubleshooting Help

Issue: Proxy Status Synchronisation Problems

Configuration Issues

Issue: Configuration File Problems

Issue: Integration Configuration

Report Generation Issues

Issue: Report Generation Failures

Issue: PDF Generation Problems

Performance Optimisation

Memory Usage Optimisation

CPU Usage Optimisation

Disk I/O Optimisation

General Debugging Tips

Enable Verbose Logging

Network Debugging

Memory Debugging

Support and Diagnostics

Log Information to Collect

Troubleshooting Support Channels

General Emergency Procedures

Troubleshooting Related Documentation