Skip to main content

Troubleshooting FAQ

Solutions to common issues encountered when running Hawkra.

Services won't start​

If one or more services fail to start after running docker compose up -d, work through the following checks:

Check the logs for the failing service:

docker compose logs <service-name>

Replace <service-name> with backend, frontend, postgres, redis, or caddy.

Verify your environment file:

Ensure your .env file contains the required variables (APP_DOMAIN and POSTGRES_PASSWORD). If you set MASTER_ENCRYPTION_KEY or JWT_SECRET yourself, a malformed value (the key must be 64 hex characters, the secret at least 32 characters) will prevent the backend from starting.

Check for port conflicts:

Caddy binds to ports 80 and 443 by default. If another process is using these ports, Caddy will fail to start:

sudo lsof -i :80
sudo lsof -i :443

Stop any conflicting services or change the port mapping in docker-compose.yml.

Check available disk space:

df -h

Docker requires sufficient disk space for images, volumes, and container logs. If the disk is full, services may fail to start or behave unpredictably.

Can't connect to the web interface​

  • Verify all services are running: docker compose ps
  • Check DNS resolution (or add an entry to /etc/hosts for local testing)
  • Verify firewall allows inbound on ports 80 and 443: sudo firewall-cmd --list-ports or sudo ufw status
  • Try accessing directly via IP to isolate DNS issues

Database connection errors​

  • Check PostgreSQL health: docker compose ps postgres (should show Up (healthy))
  • Check logs if unhealthy: docker compose logs postgres
  • Verify DATABASE_URL format: postgres://hawkra:your_password@postgres:5432/hawkra (hostname must be postgres, not localhost)
  • Check disk space on the volume (df -h)

Scans not running​

If network scans (WingSpan Scanner) fail to execute or return no results:

Verify container capabilities:

The backend container requires NET_RAW and NET_ADMIN capabilities for raw socket access. Check that your docker-compose.yml includes:

cap_add:
  - NET_RAW
  - NET_ADMIN

Verify nmap is installed (Third Party Scanners only):

docker compose exec backend which nmap

Nmap is not bundled in the image. If it is not found, install it from Admin > Settings > Scanning. It must be installed again whenever the backend container is recreated, for example after an update.

Check network reachability:

The backend container must be able to reach target networks. If targets are on a different subnet, you may need to configure Docker networking or add the backend to the appropriate network.

Email not sending​

If Hawkra is not sending emails (verification codes, password reset codes, MFA codes):

Verify SMTP settings:

Check that your SMTP configuration is correctly set in the admin dashboard under email settings. Required fields include the SMTP host, port, username, and password.

Check backend logs for SMTP errors:

docker compose logs backend | grep -i smtp

Look for authentication failures, connection timeouts, or TLS errors.

Verify outbound connectivity:

Ensure your server's firewall allows outbound connections on the SMTP port (typically 587 for TLS or 465 for SSL):

telnet smtp.your-provider.com 587

Test with a known-good configuration:

If you are unsure about your SMTP provider's settings, test with a well-documented provider like Gmail (using an app password) or Amazon SES to rule out provider-specific issues.

AI features not working​

If Ask AI or other AI-powered features return errors or do not respond:

Verify your API key:

In the admin dashboard, navigate to AI Configuration and confirm that a valid API key is set for the selected provider (Google Gemini by default), or that the OpenAI account is linked. Use Test connection on that page.

Check the LLM mode:

The LLM Mode setting (LLM_MODE) selects the provider: anthropic, deepseek, gemini, openai, or llama_router. Verify it matches the credentials you configured.

Check backend logs for AI errors:

docker compose logs backend | grep -i "ai\|llm\|gemini"

Look for authentication errors (invalid API key), rate limit messages, or network connectivity issues.

For local LLM deployments:

Verify your LLM server is running and accessible from the backend container. The backend must be able to reach the LLM server's API endpoint on the configured port.

License upload fails​

If uploading a license file through the admin dashboard fails:

Verify file integrity:

Ensure the license file was not corrupted or truncated during download. Re-download it from hawkra.io and try again.

Check the expiry date:

An expired license will be rejected on upload. Verify the license has not already passed its expiry date.

Confirm admin privileges:

Only the admin user can upload licenses. Ensure you are logged in with the account that has administrative access.

Re-download and retry:

If the file appears correct but still fails, delete the downloaded file, clear your browser cache, and download a fresh copy from your hawkra.io account.

Forgot admin password​

The initial admin password is generated automatically during the first backend startup and printed to the logs.

Check the startup logs:

docker compose logs backend | grep -i "admin password"
caution

If container logs have been rotated or the containers have been recreated multiple times, the original log entry may no longer be available. In that case, you will need to reset the admin password directly in the database.

High memory usage​

Check usage with docker stats --no-stream. Adjust the backend memory limit in your docker-compose file if needed.

WebSocket connection issues​

If real-time features (chat, live scan updates) are not working:

Verify Caddy proxying:

WebSocket connections use /api/... paths. Ensure your Caddy configuration forwards Connection: Upgrade requests under /api/* to the backend service, as the stock Caddyfile does.

Check CORS configuration:

Verify that the CORS_ALLOWED_ORIGINS environment variable in your .env file includes your domain (including the protocol):

CORS_ALLOWED_ORIGINS=https://hawkra.yourdomain.com

Check browser console:

Open your browser's developer tools and look for WebSocket connection errors in the console. Common issues include mixed content (trying to connect via ws:// on an https:// page) and CORS rejections.