Troubleshooting
Viewing Container Logs
To see and "tail" logs for all Dropzone service:
docker compose -p dz logs -fTo see and "tail" logs for a specific Dropzone service:
docker compose -p dz logs -f <service-name>For example, to view logs for the web service:
docker compose -p dz logs -f webA Container Is Unhealthy or Restarting
Check which containers are not healthy
docker compose -p dz psView the logs for the unhealthy service
docker compose -p dz logs --tail 100 <service-name>Common causes include:
Incorrect values in
config.ymlDatabase passwords that were not changed from defaults
TLS certificate/key mismatch
Insufficient system resources (CPU, memory, or disk)
Response Actions Failing (AppArmor / SELinux)
The terrarium container requires SETUID, SETGID, and AUDIT_WRITE kernel capabilities. AppArmor or SELinux may block these operations, causing Response Actions to fail.
AppArmor (Ubuntu 24.04 and later)
Ubuntu 24.04 includes AppArmor policies that restrict unprivileged user namespace creation, which block the terrarium container. For background, see Ubuntu 24.04 and Bubblewrap. To resolve this, create an AppArmor profile that allows bwrap to use user namespaces:
Then reload AppArmor:
SELinux (RHEL, CentOS, Fedora)
If SELinux is blocking container operations, check the audit log for denials:
If denials are present for the terrarium container, set the container domain to permissive:
Cannot Reach the Dropzone UI
Verify the
nginxcontainer is running and healthy:docker compose -p dz ps nginxVerify DNS resolves your hostname to the instance's IP:
dig <your-hostname>Verify port 443 is open in your security group or firewall
Verify the TLS certificate in
config.ymlmatches the hostname you are accessingCheck nginx logs:
docker compose -p dz logs nginx
OIDC Authentication Fails
Verify the
client-idandclient-secretinconfig.ymlmatch your IdP applicationVerify all OIDC endpoint URLs in the
oidc.manualsection are correct and reachable from the instanceVerify your IdP is configured to allow redirect URIs to
https://<your-hostname>Check web service logs for detailed error messages:
docker compose -p dz logs web
AI Provider Errors
Check
ai-corelogs for provider-specific error messages:
Verify the providers enabled in
ai_provider_config.yamlhave matching API keys set in theapissection ofconfig.ymlVerify the instance has outbound network access to the AI provider endpoints (see Network Requirements)
Test connectivity from the instance to your configured providers:
Validate your configured AI models:
The first command checks model name spelling. Adding
--check-connectivityalso probes each enabled model with a live API call, reporting the specific endpoint, deployment name, and API key variable that failed.To see all valid model names for a provider and generate a ready-to-paste config snippet, run:
For a full workflow for fixing and revalidating provider configuration, see Managing AI Providers.
ai-core Fails to Start
ai-core intentionally exits at startup if the configuration is invalid or any enabled model is unreachable. Check the logs first:
Common causes:
Invalid model key — a model name under
models:does not match the built-in catalog. Runai-model-tool validate-configto identify and fix the offending names before restartingAuthentication failure (401/403) — credentials are missing, incorrect, or do not have permission to access the model. Verify the API key in
config.ymland your provider account permissionsModel or deployment not found (404) — a
deployment_namein your config does not match any deployed model in your provider account. Check your provider console (e.g. Azure OpenAI Studio) to verify your deployment names and compare them against thedeployment_namevalues inai_provider_config.yaml. Checkai-corelogs to see which deployment(s) failed
If you need to get ai-core running while you debug the config, see Managing AI Providers — Recovery.
Restarting After Configuration Changes
After editing any configuration files in /opt/dropzone/deploy/, restart the deployment:
Getting Help
If the above steps do not resolve your issue, engage our Customer Success team. When reaching out, include:
The output of
docker compose -p dz psRelevant container logs (
docker compose -p dz logs --tail 200 <service-name>)Any configuration changes made since the last successful deployment
Was this helpful?