Troubleshooting

This page covers common troubleshooting steps for Canasta instances.

If the wiki is up but you're trying to inspect logs, metrics, or the OpenSearch Dashboards UI, start with Help:Observability — that's the "where to look" map. This page is the "what to do when something is wrong" catalog.

Checking instance status

To see whether your Canasta instance is running and inspect its containers / pods, volumes, ingress, and (on Kubernetes) TLS certificate state:

canasta status --id mywiki

Works for both Docker Compose and Kubernetes instances. Shows the orchestrator-native view in one shot — no need to remember docker compose ps vs. kubectl get pods -n canasta-mywiki.

Checking that wikis are reachable

canasta status tells you whether the containers are running; it does not tell you whether the wikis actually answer. A stack can be fully "up" while MediaWiki returns a 500, a wiki's URL in config/wikis.yaml is wrong, or a farm's newest wiki was never routed. canasta wiki-check closes that gap by reading the instance's configured wikis and requesting each one over HTTP:

canasta wiki-check -i mysite

It reports one line per wiki and exits non-zero if any wiki fails, which makes it usable as a post-deploy smoke test:

Checking Canasta Wiki: mysite
Wiki 'main' is reachable at https://example.com.
Wiki 'docs' could not be reached at https://docs.example.com.

Three outcomes are distinguished, and the difference matters when you are diagnosing:

• reachable — the wiki answered successfully.
• could not be reached — the host answered but the wiki did not. The wiki is genuinely down or misconfigured.
• could not be checked ... host is unreachable — the check itself could not run because the host was unreachable (DNS, SSH, network). This is not a verdict about the wiki; fix connectivity to the host first.

A wiki whose url is missing or empty in config/wikis.yaml is reported as a failure too, since an unroutable wiki is a real defect even though nothing is down.

To check a host directly rather than by instance:

canasta wiki-check --host prod1.example.com

--host and -i/--id can both be given, in which case --host wins.

The same probe backs the liveness column in canasta list, so a quick look there covers every instance at once; wiki-check is the per-wiki detail view when something in that column looks wrong.

Detecting and fixing configuration drift

Over time an instance's running containers can drift from its configuration — for example COMPOSE_PROFILES falling out of sync with the feature flags, a container left running whose profile is no longer active, or CirrusSearch configured without its Elasticsearch backend. canasta doctor reports this drift per instance:

canasta doctor

When it finds drift, canasta reconcile heals it without a disruptive restart. It re-derives COMPOSE_PROFILES from the feature flags and database mode, regenerates rendered config (such as the Caddyfile), and converges the running containers with docker compose up -d — starting anything missing and recreating only what changed, with no stop. It is idempotent and safe to run anytime:

canasta reconcile

# a single instance
canasta reconcile --id mywiki

Reconcile heals profile/runtime drift and the CANASTA_IMAGE tag; other warnings doctor prints (such as a search backend that needs enabling) name their own fix.

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. nginx or 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.
• Specifically for Cloudflare (including HTTP 525 errors and redirect loops), the right CADDY_AUTO_HTTPS setting depends on your Cloudflare SSL/TLS mode — see Help:Using Canasta with Cloudflare.

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.