Fixing a MariaDB Version Mismatch in Lando: What Happened and How We Solved It

Working with local development environments like Lando is usually very smooth, but occasionally a deeper issue surfaces, especially when databases and version upgrades are involved. This post explains a real-world problem I encountered when a Lando instance refused to connect to MariaDB, despite the database container running without any obvious errors.

If you're using Lando on Windows, particularly with Bitnami-based MariaDB images, this is an important one to understand - and it might save your project.

The Symptom: "Connection Refused" Errors Everywhere

After rebuilding a Lando environment, the site stopped working with the following error:

PDOException: SQLSTATE[HY000] [2002] Connection refused

phpMyAdmin also couldn't connect:

mysqli::real_connect(): (HY000/2002): Connection refused

What made this confusing is that the database container was running, and Lando's healthcheck passed. But anything trying to reach MariaDB through port 3306 failed instantly.

Why We Declared a MariaDB Image

The original .lando.yml configuration referenced an older Bitnami MariaDB tag:

bitnami/mariadb:10.3.39-debian-11-r5

Unfortunately, that tag was removed from Docker Hub. When Lando tried to rebuild the environment, it failed to pull the image:

manifest for bitnami/mariadb:10.3.39-debian-11-r5 not found

To resolve the missing image, we explicitly declared a replacement in .lando.yml:

services:
  database:
    type: mariadb:10.6
    overrides:
      image: bitnamilegacy/mariadb:10.6.20-debian-12-r2

This allowed the container to build again, but it introduced a much deeper issue.

The Real Cause: MariaDB Can't Skip Major Versions

Once we inspected the database logs from inside the container, the problem became clear. MariaDB printed this critical message:

[ERROR] InnoDB: Upgrade after a crash is not supported.
The redo log was created with MariaDB 10.3.39.
You must start up and shut down MariaDB 10.4 or earlier on the data directory.

In simple terms:

• The existing data directory was created using MariaDB 10.3.
• We attempted to start it with MariaDB 10.6.
• MariaDB does not allow jumping directly from 10.3 to 10.6, especially if the previous shutdown wasn't perfectly clean.

So even though the container was "running", the MariaDB server inside it never actually started. No socket, no port binding, no database - just a silent failure.

Why the Healthcheck Passed Despite the Failure

Bitnami containers include several wrapper scripts that start before the actual database daemon. These scripts run successfully even if MariaDB itself fails. That's why:

• Lando showed the database as healthy
• Docker showed the container as running
• But Drupal and phpMyAdmin still couldn't connect

Once we understood that MariaDB itself never launched, everything made sense.

The Fix: Use a Correct Transitional MariaDB Version

MariaDB needs to follow its upgrade path in the correct order. The logs even told us what to do:

"You must start up and shut down MariaDB 10.4 or earlier on the data directory."

So we switched the database image to:

services:
  database:
    type: mariadb:10.4
    overrides:
      image: mariadb:10.4

After a rebuild, MariaDB started perfectly using the existing data directory. The redo logs were upgraded correctly, the server shut down cleanly, and the whole environment came back to life.

Lessons Learned

• If a MariaDB container runs but doesn't accept connections, check the logs first.
• MariaDB cannot skip major versions during an upgrade.
• Bitnami images may require careful version matching, especially when used with existing database volumes.
• A missing or deleted Docker image tag can force you into making a version change, which may trigger this exact issue.
• On Windows (Docker Desktop + WSL2), container networking issues can disguise deeper database problems.

Final Thoughts

This was a great example of how a seemingly simple environment rebuild can expose deeper compatibility issues. Declaring a MariaDB image in .lando.yml was necessary because the original Docker tag was removed, but the replacement image introduced a version mismatch that MariaDB could not recover from.

Using MariaDB 10.4 as a transitional step resolved the issue safely without losing any data. Hopefully this helps someone else avoid hours of head scratching the next time a Lando database mysteriously refuses to connect.