OneCX Local Env - Troubleshooting - Common Issues

If the keycloak-app service is reported as unhealthy, please try to re-run the docker compose command to start the service again. In some cases, Keycloak might take a bit longer to start up, and re-running the command can help resolve the issue. This issue is more common in OneCX Local Env v1 due to differences in the performed health checks.

In some cases, specifically when services don’t have explicit dependencies defined via the depends_on directive, Docker Compose might not wait for all health checks to pass before finalizing the startup process. If you want to force Docker Compose to wait for all health checks to pass, you can use the --wait flag when starting the services. Example:

Some onecx-local-env services might take longer than others to start up and become fully operational. This can cause issues of you or a script you are running tries to access a service before it is ready. To prevent any issues it is recommended to wait for at least 30 seconds after all services are reported as healthy before accessing any service or running any import scripts. The import script for OneCX Local Env v2 has a built-in wait time of 30 seconds after all services are healthy to account for this. If you are using OneCX Local Env v1, please ensure to manually wait for at least 30 seconds after all services are healthy before running the import script.

If the import script for OneCX Local Env v2 or other access to services still fails, please try to increase the wait time to 60 seconds and restart the affected services if all else fails.