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. To connect as MediaWiki does, use the account in WIKI_DB_USER with the password in WIKI_DB_PASSWORD. This is mediawiki as of Canasta CLI 4.22.0 on Docker Compose and 4.25.2 on Kubernetes, and it can reach only the instance's wiki databases (see Database accounts).

The bundled database confines server-side file access — SELECT ... INTO OUTFILE, LOAD DATA INFILE, and LOAD_FILE() — to the /var/lib/mysql-files directory inside the db container (Canasta CLI 4.21.0 and later). That directory starts empty and is not a persistent volume. A statement that reads or writes a file anywhere else fails with an error mentioning the --secure-file-priv option. To move a wiki's data in or out, use canasta export and canasta import instead.

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

"No site is served at this address", "This site is not running", or 429 from a Compose instance

• These come from the host's HAProxy edge. See HAProxy edge: Troubleshooting.

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
• The HAProxy edge answers No site is served at this address. when no instance serves the hostname on that port. Check that the port in the URL matches the instance's HTTPS_PORT (or HTTP_PORT with TLS_MODE=off).

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), the instance must be served over plain HTTP behind it. Run canasta config set -i myinstance TLS_MODE=off. See Common tasks: Deploying behind a reverse proxy for details.
• Specifically for Cloudflare (including HTTP 525 errors and redirect loops), the right TLS_MODE 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.

A command fails with "a restore of instance '<id>' is in progress"

backup restore, delete, start, stop and restart hold a lock on the instance while they run, so two of them can't act on it at once. The message names the command that holds the lock and when it started. Wait for it to finish and run your command again. The lock is released when that command exits, even if it was interrupted, so it can't be left behind by a crash.

canasta upgrade says an instance "stays on the database root account"

The upgrade moves instances onto MediaWiki's own database account (Docker Compose since Canasta CLI 4.22.0, Kubernetes since 4.25.2). It leaves an instance on root when a settings file sets $wgDBuser or $wgDBpassword, or when the database server holds a database that no wiki declares. The message names the file or the databases. Remove the setting, or declare each database a wiki uses with canasta backup databases add and drop the rest. The next upgrade then tries again. See Upgrading.

canasta list shows an instance as UNHEALTHY

As of Canasta CLI 4.25.1, canasta list shows UNHEALTHY rather than RUNNING when the instance's web container is crash-looping or failing its health check, or, on Kubernetes, when a web pod is not ready after crashing. Run canasta doctor -i <id> for the details: its Web container section gives the container's state, last exit code and restart count, and the startup error from the web log with its fix, when it recognizes one; otherwise it shows the last lines of the log. The causes and fixes are the same as in the next entry.

start, restart or upgrade fails because the web container never becomes healthy

The error leads with the cause the web container logged, when it recognizes one, followed by a hint and the last lines of the web log. The most common cause is a wiki that loads an extension or skin whose files are not there — for example, after an upgrade, an extension the new image no longer includes. The error names the extension. Disable it with canasta extension disable <name> -i <id> (add --wiki <wiki> if only one wiki enables it), which works while the container is restarting, or add its files under the instance's extensions/ directory. If a settings file loads it with wfLoadExtension(), remove that line instead. Then run canasta restart, or canasta upgrade again. On a Kubernetes instance managed through gitops, disable only stages the change; run canasta gitops push and canasta gitops sync to deploy it. During an upgrade, the other instances are still upgraded, and the summary names the one that failed.

A warning that the web container's startup composer update failed

The container started, but the packages added in config/composer.local.json are not installed. The warning gives the first line of the failure and the command that prints the full record from config/persistent/composer-update.failed. Fix the dependency it names — in config/composer.local.json or in an extension's composer.json — and run canasta restart. See Composer dependencies.