Nextcloud MariaDB Docker DNS Failure on ZimaOS: Fix

This January 2026 Nextcloud/MariaDB thread is one of the clearest examples of why container networking should be diagnosed layer by layer. The user installed separate Nextcloud and MariaDB apps, MariaDB reached a healthy “ready for connections” state, but Nextcloud failed during initial setup with getaddrinfo for mariadb failed. Reinstalling both apps and deleting their folders did not change the error.

The breakthrough came when the community tested the MariaDB container's actual Docker IP. Nextcloud began installing immediately. That proved the database server, credentials, and TCP path were basically functional while the hostname mariadb was not resolving from the Nextcloud container.

The User Wanted a Separate MariaDB Database for Nextcloud

Early replies discussed alternatives such as an all-in-one Nextcloud image with PostgreSQL bundled inside, or manually creating a MariaDB database and user through phpMyAdmin. Those suggestions were not the final problem. The source user already had MariaDB running and needed Nextcloud to reach it.

MariaDB Logs Showed the Database Was Healthy

MariaDB container log on ZimaOS reaching ready for connections and listening on port 3306 — The database log reached a normal ready-for-connections state, making a broken MariaDB server an increasingly unlikely explanation.

The community correctly advised against repeatedly changing MariaDB passwords and environment variables after the database had already initialized. Many database images apply initialization variables only on the first creation of the data directory.

The Database Host Must Be Reachable from Inside Nextcloud

During Nextcloud's initial setup, the database host field can contain a hostname and port such as:

mariadb:3306

That only works when Docker networking provides name resolution for mariadb from the Nextcloud container.

getaddrinfo for mariadb failed Is a DNS-Style Container Error

The key error was:

php_network_getaddresses: getaddrinfo for mariadb failed

This happens before MariaDB can accept or reject a username and password. If the name cannot be resolved to an IP address, database credentials are not yet being evaluated.

Both Apps Saying “Bridge” Did Not Solve Name Resolution

The source user confirmed that both applications showed Bridge networking in ZimaOS, but mariadb still did not resolve. This is an important Docker nuance: containers attached independently to Docker's default bridge do not automatically get the same service-name DNS behavior as services attached to a user-defined bridge network.

Therefore, “both say bridge” is not sufficient proof that one container can resolve the other's container name.

A Clean Reinstall Did Not Fix the Network Behavior

The user uninstalled both Nextcloud and MariaDB, deleted their folders, and installed them again from scratch. The same hostname error returned. This negative test is useful because it shows the problem was not simply stale MariaDB data or a one-time bad password.

A Nextcloud Local-Access Warning Was a Separate Issue

Nextcloud log on ZimaOS reporting that a local host was not connected because it violates local access rules — The source thread also showed a Nextcloud local-access rule warning, but it occurred at a different layer from the unresolved MariaDB hostname.

The user found an online suggestion to enable allow_local_remote_servers. Applying that setting during initial setup caused Nextcloud to stop starting correctly. The community explained that this option addressed a different Nextcloud security rule and did not fix Docker name resolution.

The Community Then Shifted to Direct Docker Network Tests

The responder requested checks for:

whether both containers were running;
the actual network mode reported by Docker;
whether Nextcloud could resolve or ping mariadb;
the MariaDB container's current Docker IP.

This is the correct escalation after configuration screenshots stop explaining the behavior: test the connection from the same network namespace where Nextcloud is running.

Using the MariaDB Container IP Made Nextcloud Install

The decisive test was to replace mariadb:3306 temporarily with the MariaDB container's Docker IP and port. The source user replied that Nextcloud was then installing.

The responder summarized the result clearly:

mariadb:3306 failed;
the direct Docker IP on port 3306 worked immediately.

That is strong evidence for a container-name resolution problem.

A Direct Container IP Is a Valid Diagnostic Workaround

Using the IP proves that the database can be reached and allows the installation to proceed. For the source case, it was an effective workaround.

But automatically assigned container IPs can change when a container is recreated, removed, or attached to a different network. A setup that depends permanently on 172.17.x.x can break later without any Nextcloud or MariaDB configuration change.

A User-Defined Docker Network Is a Better Long-Term Design

The more robust architecture is to attach Nextcloud and MariaDB to the same user-defined Docker network and use a stable service or container name for the database host. Docker provides embedded DNS on user-defined networks specifically for this purpose.

Current ZimaOS native YAML editing makes this kind of network definition easier than it was when the source thread was created. Use the current ZimaOS Compose configuration model when building a shared Nextcloud and MariaDB network.

Preserve MariaDB Data Deliberately

If MariaDB already contains a working Nextcloud database, do not delete its persistent data directory merely to change Docker networking. Network membership can be changed without recreating the database contents.

Before any migration, back up the database and record the current user, database name, and volume mapping.

Do Not Disable Nextcloud Security Controls to Repair Docker DNS

Settings such as trusted domains, local remote server access, and reverse-proxy configuration protect Nextcloud at the HTTP/application layer. They should be changed only when the corresponding Nextcloud error requires them.

A getaddrinfo error for the database hostname belongs to the Docker network layer.

A Better Diagnostic Tree

Confirm MariaDB is running and listening on 3306.
Confirm the intended database exists and credentials are known.
Test whether Nextcloud can resolve the database hostname.
If hostname resolution fails, test the database container IP.
If IP works, fix the Docker network rather than changing database passwords.
Move both containers to a stable user-defined network for a durable hostname.

Nextcloud and MariaDB FAQ

Was MariaDB itself broken?

No. Its log showed it was ready for connections.

What did getaddrinfo for mariadb failed mean?

Nextcloud could not resolve the database hostname before it even reached the authentication stage.

What confirmed the diagnosis?

Using the MariaDB container's direct Docker IP allowed Nextcloud to begin installing.

Should the direct container IP be the permanent database host?

It can work, but a shared user-defined Docker network with stable name resolution is more robust.

Did reinstalling both apps fix the issue?

No. The source user performed a clean reinstall and the same hostname-resolution error returned.