Troubleshooting

Troubleshooting

Use this guide to diagnose common LogForge issues quickly.

Quick reference

• docker compose ps -" verify containers are healthy.
• docker compose logs <service> -" inspect runtime errors.
• docker exec -it logforge-backend /bin/sh -" open a shell for deeper inspection.

Common issues

Frontend cannot reach backend

• Ensure the backend service is running: docker compose logs logforge-backend.
• Check network: both services must share the logforge-network bridge.
• Confirm VITE_BACKEND_SERVICE_HOST and PORT match compose service names/ports.
• If using a reverse proxy, update CORS origins (CORS_ORIGINS env var) to include the proxy domain.

Alerts not firing

• Verify the rule is enabled and scoped to the correct containers.
• Inspect alert-engine-backend logs for evaluation errors or cooldown messages.
• Confirm the triggering condition actually occurs (use the rule simulator with historical logs).
• Ensure clock skew between services is minimal; NTP recommended.

Notifications failing

• Open the Notifier UI -> Delivery History to see response codes.
• Validate that required environment variables or secrets are mounted (SMTP credentials, webhook tokens).
• Check outbound network restrictions (firewall, proxy) that might block the destination.
• Use the Send Test button to reproduce outside of automation rules.

Automation actions not executing

• Backend requires Docker socket access; confirm /var/run/docker.sock is mounted and accessible.
• Review guardrail settings (cooldowns, max executions) to ensure actions are not being suppressed.
• For script actions, confirm the script path exists inside the container and is executable (chmod +x).

High resource usage

• Limit log streaming with filters to avoid pulling entire histories.
• Adjust Alert Engine polling intervals or disable noisy rules temporarily.
• Check container memory/CPU via docker stats and consider allocating more resources.

Upgrades/auto-update issues

• logforge-autoupdate logs will show download or permission errors; ensure it retains socket access.
• If automatic upgrades fail, fall back to manual docker compose pull && docker compose up -d and monitor for schema migrations.

Getting more help

• Search existing GitHub issues or open a new ticket with diagnostic logs.
• Include compose overrides, custom scripts, and rule exports when reporting complex problems.
• For commercial support, contact the LogForge team via the Premium portal.

Return to the Overview for architecture context or dive into other wiki sections as needed.