Troubleshooting

Common issues and how to resolve them.

ClickHouse won't start

Almost always kernel limits. Confirm vm.max_map_count=262144 and the nofile limits (Install hardening), then restart the ClickHouse service.

A checker isn't running on a lead

External checkers only run when the flow threshold or a Custom Rule needs their signal. Add the checker to a rule, or lower the threshold, to force it.

OxaPay webhook not activating a license

Callbacks aren't sent to private networks. Ensure the callback_url is public (HTTPS) and the merchant key matches, so the HMAC verifies.

502 right after an update or reboot

The API runs database migrations on start (alembic upgrade head), so it's briefly unavailable while they apply — especially on the first boot of a new version. Give it a minute; if it persists, check the api logs.

The disk is filling up

Reclaim space from old Docker layers with docker system prune, and cap analytics growth with a retention window in Settings. If ClickHouse is the culprit, it's the analytics volume — trimming old events frees it without touching leads (those live in Postgres).

Getting help — share logs

Grab the relevant service logs and send them to us; we don't need access to your box. Then reach the team on Telegram or email.

docker compose logs --tail=200 api worker