For the complete documentation index, see llms.txt. This page is also available as Markdown.

Troubleshooting

Viewing Container Logs

To see and "tail" logs for all Dropzone service:

docker compose -p dz logs -f

To 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 web

A Container Is Unhealthy or Restarting

  1. Check which containers are not healthy

docker compose -p dz ps
  1. View the logs for the unhealthy service

docker compose -p dz logs --tail 100 <service-name>

Common causes include:

  • Incorrect values in config.yml

  • Database 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.

This container runs customer-supplied python code. The container switches to a separate user prior to running the customer-supplied code to provide container integrity, which is why these permissions are needed.

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 nginx container is running and healthy: docker compose -p dz ps nginx

  • Verify 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.yml matches the hostname you are accessing

  • Check nginx logs: docker compose -p dz logs nginx

OIDC Authentication Fails

  • Verify the client-id and client-secret in config.yml match your IdP application

  • Verify all OIDC endpoint URLs in the oidc.manual section are correct and reachable from the instance

  • Verify 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-core logs for provider-specific error messages:

  • Verify the providers enabled in ai_provider_config.yaml have matching API keys set in the apis section of config.yml

  • Verify 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-connectivity also 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 AWS Bedrock connectivity, use the AWS CLI: aws bedrock-runtime invoke-model .... Bedrock does not respond to unauthenticated HTTPS probes.

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. Run ai-model-tool validate-config to identify and fix the offending names before restarting

  • Authentication failure (401/403) — credentials are missing, incorrect, or do not have permission to access the model. Verify the API key in config.yml and your provider account permissions

  • Model or deployment not found (404) — a deployment_name in 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 the deployment_name values in ai_provider_config.yaml. Check ai-core logs 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 ps

  • Relevant container logs (docker compose -p dz logs --tail 200 <service-name>)

  • Any configuration changes made since the last successful deployment

Was this helpful?