# 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](Overview.md) for architecture context or dive into other wiki sections as needed.