AI Assistant On-Prem Troubleshooting

Use this page to diagnose common issues in an AI Assistant on-prem Docker deployment. For the full troubleshooting reference, see the AI Assistant Docker Repository.

First Checks

1. docker compose ps to see container status.
2. docker compose logs <service> to read the logs for a service.
3. Confirm the required .env values are set.
4. Restart the affected service.

Health Endpoints

Service	Endpoint	Expected response
release-assistant	/actuator/health/liveness	HTTP 200, liveness UP
llm-service-api	/llm/utility/ping	HTTP 200 with an empty body (judge by the status code, not the body)

note

On some hosts localhost resolves to IPv6 first, so a health check can return Empty reply from server even when the service is healthy. Use 127.0.0.1 instead of localhost.

Common Issues

Symptom	Likely cause	Resolution
llm-service-dbinit exits non-zero	Database unreachable or missing provider config	Verify the database settings and LLM_SERVICE_DEFAULT_PROVIDER_CONFIG.
Release Assistant liveness is DOWN	Missing provider config or downstream connectivity issue	Set the provider config and verify the LLM Service is reachable.
AI Assistant sign-in fails	Release is not configured for OIDC, or the issuer does not match	Configure OIDC in Release and verify OIDC_ISSUER_URI.
AI Assistant returns no data although services look healthy	Release is unlicensed or unhealthy, or the built-in MCP server is disabled	Confirm Release is licensed and healthy, and that the MCP server is enabled. See AI Settings.
LLM provider errors or timeouts	Invalid credentials, blocked egress, or the model is unavailable	Check the provider credentials in LLM_SERVICE_DEFAULT_PROVIDER_CONFIG and verify outbound access to the provider endpoint.
Browser mixed-content error	The Release Assistant URL is HTTP while Release is HTTPS	Configure the Release Assistant URL as HTTPS.
Cannot connect to the Docker daemon	Docker Engine or Docker Desktop is not running	Start Docker and wait until docker info succeeds, then retry.
Health check returns Empty reply from server	localhost resolves to IPv6 first	Use 127.0.0.1 instead of localhost.

Startup and Crash-Loop Issues

The containers use a restart policy, so a service that fails to start keeps restarting. In docker compose ps, a crash-loop shows as an uptime that repeatedly resets to a few seconds, rather than a steady Up status.

Read the logs and look for the root cause in the Caused by: chain:

docker compose logs --tail=500 release-assistant 2>&1 | grep -iE "caused by|failed|invalid" | tail -30

Common root causes:

Log message	Cause	Resolution
scope " dai-svc" contains invalid characters	A stray space in the scope list. The value is split on the comma without trimming, so "openid, dai-svc" yields a scope with a leading space, which the token validator rejects.	Set OAUTH2_SCOPES="openid,dai-svc" with no space after the comma.
OIDC_ISSUER_URI unreachable / token validation fails on startup	The issuer URL resolves or routes to an address the container cannot reach	Set OIDC_ISSUER_URI to an address that resolves from inside the Docker network and matches the issuer the browser receives.
License file ... missing preamble (local Release container only)	The xl-release-license.lic file is empty or invalid	Provide a valid Release license, then recreate the Release container. A customer-managed Release manages its own license.

Connectivity Issues

Symptom	Likely cause	Resolution
UnknownHostException for the Release, Assistant, or identity hostname	The FQDN does not resolve on the host or inside the container	Add the hostnames to DNS, or to the host file. See Verify Hostname Resolution.
Assistant cannot reach the embedded MCP endpoint	Wrong RELEASE_PUBLIC_URL host or port	Confirm RELEASE_PUBLIC_URL is reachable and that ${RELEASE_PUBLIC_URL}/s/mcp responds.
Chat fails with an audience or authorization error	The user token is missing the dai-svc scope or the Audience mapper is not configured	Verify the OIDC client setup. See Authentication.

Inspect the LLM Service API

The LLM Service serves a Swagger UI at the /llm/docs path of its service address. Use it to query the service directly, such as to confirm which models are available. For example, http://<llm-service-host>:9000/llm/docs#/models/list_models opens the endpoint that lists all available models.

The endpoints require a bearer token. Request a token from the token endpoint of your identity provider, using the client settings from your OIDC configuration. In the Swagger UI, select Authorize and paste the token.

Slow Startup on Apple Silicon

On Apple Silicon (arm64) hosts, the images run under amd64 emulation, and Docker logs a warning such as platform (linux/amd64) does not match ... arm64. This is a warning, not an error. Expect slower boots (up to a couple of minutes for Release) while the containers become healthy.

For deployment steps, see Production Deployment Using Docker.