Troubleshooting

Table of Contents

1. Common Issues

Symptom Application fails to start with connection refused errors

Symptom	Application fails to start with connection refused errors
Cause	Database is unreachable or credentials are incorrect
Solution	Verify that `MAIN_DB_URL`, `UI_DB_URL`, and `CLICKHOUSE_DB_URL` are correct Confirm database services are running and accepting connections Check that `MAIN_DB_USERNAME` / `MAIN_DB_PASSWORD` and corresponding UI DB credentials are valid

Cause

Database is unreachable or credentials are incorrect

Solution

Verify that MAIN_DB_URL, UI_DB_URL, and CLICKHOUSE_DB_URL are correct
Confirm database services are running and accepting connections
Check that MAIN_DB_USERNAME / MAIN_DB_PASSWORD and corresponding UI DB credentials are valid

Symptom Warnings about Hazelcast client unable to connect

Symptom	Warnings about Hazelcast client unable to connect
Cause	Hazelcast cluster is not running or address is misconfigured
Solution	Verify `HAZELCAST_CLUSTER_NAME` and `HAZELCAST_ADDRESS` are correct Ensure Hazelcast cluster members are running and accessible from the application host Check firewall rules for Hazelcast ports (default: 5701)

Cause

Hazelcast cluster is not running or address is misconfigured

Solution

Verify HAZELCAST_CLUSTER_NAME and HAZELCAST_ADDRESS are correct
Ensure Hazelcast cluster members are running and accessible from the application host
Check firewall rules for Hazelcast ports (default: 5701)

Symptom Slow or timed-out responses on Dashboard, Device Groups, or Reports pages

Symptom	Slow or timed-out responses on Dashboard, Device Groups, or Reports pages
Cause	Large data volume in ClickHouse or missing aggregated tables
Solution	Review the `Keep data (days)` setting in Settings > General to limit data retention Verify that `kpi_data_aggregated` and `kpi_data_latest` tables are being populated Check ClickHouse server performance and resource allocation

Cause

Large data volume in ClickHouse or missing aggregated tables

Solution

Review the Keep data (days) setting in Settings > General to limit data retention
Verify that kpi_data_aggregated and kpi_data_latest tables are being populated
Check ClickHouse server performance and resource allocation

Symptom Scheduled tasks are not executing

Symptom	Scheduled tasks are not executing
Cause	Quartz DB connection issues or job store misconfiguration
Solution	Verify Quartz datasource configuration in `application.yml` Check that the Quartz DB tables exist and are accessible Review application logs for Quartz-related errors

Cause

Quartz DB connection issues or job store misconfiguration

Solution

The application uses SLF4J with Logback. Log levels can be adjusted via application.yml or environment variables:

logging:
  level:
    com.friendly.tr069.ftacs.qoe.monitoring.web: DEBUG
    org.springframework: INFO
    org.hibernate: WARN

When running with Docker, a debug port is exposed on 5005:

# Connect with a remote debugger on port 5005

For local development:

./gradlew bootRun --debug-jvm

Alarm processing — Search for AlarmProcessor or ThresholdProcessor in logs
Data sync tasks — Search for SyncTask or QoeCpeInfoSyncTask
JMS messages — Search for JmsConsumer or MessageSender
Cache operations — Search for CpeCache or KpiCache