Troubleshooting the Compose setup

This section covers common issues and their solutions when running Cadenza with Docker Compose.

Docker Group Membership

If you receive permission errors when running Docker commands, you may need to add your user to the docker group:

sudo usermod -a -G docker $USER

After adding yourself to the group, log out and log back in for the changes to take effect.

For more details, see the Docker documentation on managing Docker as a non-root user.

Port Already in Use

If you get an error that port 8080 is already in use:

Check what’s using the port:
```
sudo lsof -i :8080
```
Either stop the conflicting service or change the port mapping in your compose file:
```
services:
  cadenza:
    ports:
      - "8081:8080"  # Use different host port
```

Database Migration Errors

If migration fails, check the migration service logs:

docker compose logs migrate

Common issues:

Configuration file not found or invalid
Insufficient permissions on volume mounts
Database schema incompatibility (check Cadenza version compatibility)

Container Fails to Start

If a container repeatedly fails to start:

Check container logs for error messages:
```
docker compose logs
```
Verify the compose file syntax:
```
docker compose config
```
Ensure all required environment variables are set

Check that the image tag exists in the registry:

docker pull registry-ext.disy.net/cadenza/cadenza-web:10.5.x-release

Volume Permission Errors

If Cadenza fails to start with permission denied errors, the container user (UID 1001, GID 1001) may not have access to mounted directories.

See the Volume Permissions and File Access section in Advanced Topics for detailed information on how to resolve permission issues.

DNS Resolution Issues

On systems running systemd, containers may have difficulty resolving DNS names. This is typically caused by systemd-resolved which creates a /etc/resolv.conf using a local DNS cache.

Symptoms:

Container cannot access external services
Network connectivity issues
DNS resolution failures in logs

Solution: Configure Docker to use a specific DNS server by editing /etc/docker/daemon.json:

{
  "dns": ["8.8.8.8", "8.8.4.4"]
}

Then restart the Docker daemon:

sudo systemctl restart docker

Creating PDF Report Fails

The creation of the PDF report can fail for multiple reasons and it is not possible to cover all cases in the documentation. This section documents known cases and adds the solution.

Wrong or missing Cadenza URL

If the PDF creation fails with an error message like the following, the external Cadenza URL has not been configured properly:

==== Browser logs (3) ====
  [2026-04-22T07:42:17.636Z] [SEVERE] http://cadenza:8080/cadenza/repositories/... - Access to XMLHttpRequest at 'https://myportal.example.org/auth/realms/myrealm/protocol/openid-connect/auth/...' (redirected from 'http://cadenza:8080/cadenza/workbooks/...') from origin 'http://cadenza:8080' has been blocked by CORS policy: Response to preflight request doesn't pass access control check: No 'Access-Control-Allow-Origin' header is present on the requested resource.

This error message is misleading and caused by a failing login attempt with the mechanism used for workbook reporting. See Running with Docker Compose for the necessary configuration (look for basicweb.publicCadenzaUrl and workbookreport.cadenzaUrl).

Getting Help

If you encounter issues not covered here:

Check the container logs carefully for error messages
Review the Cadenza application logs in the mounted logs directory
Verify your configuration against the examples in this documentation
Contact Cadenza support with relevant log excerpts and your compose file configuration