Troubleshooting

Common errors and solutions when using kafka-log-analyzer.

Error Code Reference

Error Code	Description	Common Cause
INVALID_INPUT	Missing or invalid input parameters	Required field not provided
FILE_NOT_FOUND	Log file does not exist	Wrong file path or insufficient permissions
PROMETHEUS_UNAVAILABLE	Cannot connect to Prometheus	Prometheus URL incorrect or service down
LOKI_UNAVAILABLE	Cannot connect to Loki	Loki URL incorrect or service down
HOOK_ERROR	Hook server operation failed	Port conflict or webhook misconfiguration
PUSH_ERROR	Push notification failed	Webhook URL invalid or target unreachable
JIRA_ERROR	JIRA integration failed	JIRA URL/token incorrect
DATABASE_ERROR	SQLite operation failed	Storage directory unwritable

Python Dependency Issues

kafka-log-analyzer requires Python 3.8+ for log analysis.

Python not found

Error: Python script failed: python3: command not found

Solution:

1. Install Python 3.8+:

   # macOS
   brew install python3
   
   # Ubuntu/Debian
   sudo apt install python3
   
   # RHEL/CentOS
   sudo yum install python3

2. Or set pythonLocation environment variable if using a custom install:

   export pythonLocation=/path/to/python/installation

Wrong Python version

Error: Python script failed: SyntaxError: invalid syntax

Solution: Ensure Python 3.8+ is installed:

python3 --version
# Should show 3.8.x or higher

Connection Troubleshooting

Prometheus Connection Failed

WARN: Prometheus unavailable: fetch failed

Checklist:

1. Verify Prometheus is running:

   curl http://localhost:9090/-/healthy

2. Check PROMETHEUS_URL environment variable:

   echo $PROMETHEUS_URL
   # Should be like http://prometheus-server:9090

3. Ensure network connectivity from the analyzer host to Prometheus.

Loki Connection Failed

WARN: Loki unavailable: Invalid URL

Checklist:

1. Verify Loki is running:

   curl http://localhost:3100/ready

2. Check LOKI_URL environment variable:

   echo $LOKI_URL
   # Should be like http://loki-server:3100

Webhook Push Failed

Error: Webhook URL validation failed: URL must start with https://

Or:

Error: Webhook URL validation failed: URL resolves to private IP range

Checklist:

1. Webhook URLs must use https:// (not http://).
2. URLs cannot resolve to private IP ranges (127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16).
3. Verify FEISHU_WEBHOOK_URL or SLACK_WEBHOOK_URL environment variables.

File Analysis Issues

File not found

Error: File not found: /path/to/server.log

Solution:

1. Verify the file exists:

   ls -la /path/to/server.log

2. Use absolute paths to avoid ambiguity.

3. Ensure the path does not contain ../ (path traversal is blocked for security).

Empty analysis results

If analyze_log returns zero events:

1. Check that log format matches expected patterns (text or JSON Kafka logs).
2. Verify the log file contains Kafka-related entries.
3. Try with --debug flag for detailed parsing information:

   npx kafka-log-analyze analyze server.log --debug

Path traversal error

Error: Invalid path: path traversal detected

Solution: Use direct paths without ../ sequences. The analyzer blocks path traversal for security.

Storage Issues

SQLite database error

Error: DATABASE_ERROR: unable to open database file

Checklist:

1. Check SQLITE_PATH environment variable:

   echo $SQLITE_PATH
   # Default: ./storage/kafka-analyzer.db

2. Ensure the storage directory is writable:

   mkdir -p ./storage
   chmod 755 ./storage

3. If persistence is not needed, the analyzer continues to work without storage.

Hook Server Issues

Port already in use

Error: HOOK_ERROR: listen EADDRINUSE: address already in use :::3000

Solution: Use a different port:

npx kafka-log-analyze hooks --port 3001

Or set PAGERDUTY_WEBHOOK_PORT environment variable.

Hook not triggering analysis

1. Verify the hook server is running:

   curl http://localhost:3000/hooks/health

2. Check webhook payloads match expected format (Grafana unified alerting or PagerDuty Events API v2).

3. Review dedup settings — alerts within the TTL window are suppressed:

   HOOK_DEDUP_WINDOW_MS=30000  # 30 seconds default