Troubleshooting

This page covers common troubleshooting steps for Canasta instances.

Checking container status

To see if your Canasta containers are running:

cd /path/to/instance
docker compose ps

Viewing container logs

To view logs from the web container:

cd /path/to/instance
docker compose logs web

To follow logs in real-time:

docker compose logs -f web

To view logs from all containers:

docker compose logs

Enabling the MediaWiki debug log

The exception, error, and fatal log files are created automatically. For more verbose debugging, enable the full debug log by adding this to a settings file (e.g., config/settings/global/Debug.php):

<?php
$wgDebugLogFile = '/var/log/mediawiki/debug.log';

Log file locations

For more detailed debugging, you can access log files inside the container:

Log	Description	Command
Exceptions	Uncaught exceptions (exists by default)	`docker compose exec web tail -f /var/log/mediawiki/exception.log`
Errors	PHP errors (exists by default)	`docker compose exec web tail -f /var/log/mediawiki/error.log`
Fatal errors	Fatal errors (exists by default)	`docker compose exec web tail -f /var/log/mediawiki/fatal.log`
MediaWiki debug	Verbose debug log (opt-in, see above)	`docker compose exec web tail -f /var/log/mediawiki/debug.log`
Apache error	PHP errors and Apache warnings	`docker compose exec web tail -f /var/log/apache2/error_log.current`
Apache access	HTTP request log	`docker compose exec web tail -f /var/log/apache2/access_log.current`

Accessing the database

To connect to the MariaDB database directly:

canasta maintenance exec -s db mariadb -u root -p

Enter the root database password from your .env file (MYSQL_PASSWORD) when prompted.

Running commands inside containers

Use canasta maintenance exec to run commands inside a running container. This works with both Docker Compose and Kubernetes instances.

To list running services:

canasta maintenance exec

To get a shell inside the web container:

canasta maintenance exec -s web

To run a specific command (the default service is web):

canasta maintenance exec php -v

To run a command in a different container:

canasta maintenance exec -s db mariadb -u root -p

Warning: Files created or modified directly inside a container are not persisted across restarts. Only mounted volumes (.env, config/, extensions/, skins/, images/) survive a canasta stop/canasta start cycle. Use canasta maintenance exec for debugging and inspection, not for permanent configuration changes — use canasta config set, settings files, or wikis.yaml instead.

Common issues

Instance fails with "Canasta instance with the ID already exists"

An instance with that ID is already registered. Use canasta list to see existing instances, or choose a different ID.

Cannot connect to Docker

Ensure Docker is running: systemctl status docker
Ensure your user has Docker access (on Linux: sudo usermod -aG docker $USER, then log out and back in)

Wiki not accessible after creation

Check that containers are running: docker compose ps
Verify the domain/URL configuration in config/wikis.yaml
Check container logs for errors: docker compose logs web

Wiki not accessible on non-standard ports

When using non-standard ports, the port must be included in the URL you use to access the wiki in your browser (e.g., https://localhost:8443, not https://localhost)
The port must also appear in the URL in config/wikis.yaml (e.g., localhost:8443 or localhost:8443/wiki2)
This applies to both path-based and subdomain-based wikis

SSL/TLS errors when running behind a reverse proxy or load balancer

If your server is already behind something that terminates SSL (e.g. Cloudflare, nginx, a cloud load balancer), Caddy's automatic HTTPS will conflict with it. Run canasta config set -i myinstance CADDY_AUTO_HTTPS=off. See Common tasks: Deploying behind a reverse proxy for details.

Permission denied errors

Ensure your user is in the docker group and the web server group for your distribution (on Linux: sudo usermod -aG docker,www-data $USER, then log out and back in)
The docker group is needed for Docker access; the web server group is needed because the web container shares the config/ directory with the host
The web server group name varies by Linux distribution. The following table lists the most common examples (this is not an exhaustive list):

Distribution	Web server group
Debian, Ubuntu	`www-data`
Arch Linux, CachyOS	`http`
RHEL, CentOS, Fedora	`apache`
openSUSE, SUSE	`www`

If you are unsure which group to use, run getent group 33 to see which group name corresponds to GID 33 on your system. If no result is returned, your distribution may use a different GID for the web server — check your distribution's documentation.

Ensure the instance directory has proper ownership

Starting up Canasta repo the first time leads to a "Error 503 Backend fetch failed / Guru Meditation" error

This is an error that Varnish returns, most likely because it cannot access the Canasta container. Wait a few minutes for it to go away. If after 10 minutes it does not go away, try to restart your Canasta stack.