What causes "MYSQL_DATABASE not found" in coollabsio/coolify?

Add MYSQL_DATABASE= to the service database's environment in Coolify and redeploy the service.

coollabsio/coolify · error · Exception

MYSQL_DATABASE not found

Error message

MYSQL_DATABASE not found

What it means

For MySQL databases that belong to a service, DatabaseBackupJob runs docker exec <container> env and parses the MYSQL_DATABASE= line to determine which database(s) to dump. If no line starts with MYSQL_DATABASE=, it throws — without that value the job cannot name a database to back up. (The equivalent MARIADB_DATABASE is handled in the mariadb branch.)

Source

Thrown at app/Jobs/DatabaseBackupJob.php:191

                    $commands[] = "docker exec $this->container_name env | grep MYSQL_";
                    $envs = instant_remote_process($commands, $this->server, true, false, null, disableMultiplexing: true);
                    $envs = str($envs)->explode("\n");

                    $rootPassword = $envs->filter(function ($env) {
                        return str($env)->startsWith('MYSQL_ROOT_PASSWORD=');
                    })->first();
                    if ($rootPassword) {
                        $this->database->mysql_root_password = str($rootPassword)->after('MYSQL_ROOT_PASSWORD=')->value();
                    }

                    $db = $envs->filter(function ($env) {
                        return str($env)->startsWith('MYSQL_DATABASE=');
                    })->first();

                    if ($db) {
                        $databasesToBackup = str($db)->after('MYSQL_DATABASE=')->value();
                    } else {
                        throw new \Exception('MYSQL_DATABASE not found');
                    }
                } elseif (str($databaseType)->contains('mariadb')) {
                    $this->container_name = "{$this->database->name}-$serviceUuid";
                    $this->directory_name = $serviceName.'-'.$this->container_name;
                    $commands[] = "docker exec $this->container_name env";
                    $envs = instant_remote_process($commands, $this->server, true, false, null, disableMultiplexing: true);
                    $envs = str($envs)->explode("\n");
                    $rootPassword = $envs->filter(function ($env) {
                        return str($env)->startsWith('MARIADB_ROOT_PASSWORD=');
                    })->first();
                    if ($rootPassword) {
                        $this->database->mariadb_root_password = str($rootPassword)->after('MARIADB_ROOT_PASSWORD=')->value();
                    } else {
                        $rootPassword = $envs->filter(function ($env) {
                            return str($env)->startsWith('MYSQL_ROOT_PASSWORD=');
                        })->first();
                        if ($rootPassword) {
                            $this->database->mariadb_root_password = str($rootPassword)->after('MYSQL_ROOT_PASSWORD=')->value();

View on GitHub (pinned to 70b9acc424)

Solutions

Add MYSQL_DATABASE=<name> to the service database's environment in Coolify and redeploy the service.
Verify inside the container: docker exec <container> env | grep MYSQL_DATABASE — the line must exist and be non-empty.
If you need multiple databases, set MYSQL_DATABASE to the primary one and back up others explicitly, since the job backs up the value it finds.

Example fix

# before: service database container lacks the variable
environment:
  - MYSQL_ROOT_PASSWORD=rootpw

# after: name the database to back up
environment:
  - MYSQL_ROOT_PASSWORD=rootpw
  - MYSQL_DATABASE=main

Defensive patterns

Strategy: validation

Validate before calling

// Pre-flight inside the job before failing hard
$envOutput = instant_remote_process(["docker exec {$this->container_name} env"], $this->server, true, false, null, disableMultiplexing: true);
if (! str($envOutput)->explode("\n")->contains(fn ($line) => str($line)->startsWith('MYSQL_DATABASE='))) {
    // surface actionable feedback instead of a bare exception
    throw new \RuntimeException("MYSQL_DATABASE is not set on container {$this->container_name}; set it in the service environment.");
}

Try / catch

try {
    // ... backup logic that reads MYSQL_DATABASE ...
} catch (\Exception $e) {
    if ($e->getMessage() === 'MYSQL_DATABASE not found') {
        // notify with a fix hint; mark execution failed with context
        $this->backup->executions()->create([
            'status' => 'failed',
            'message' => 'Set MYSQL_DATABASE in the service database environment and redeploy.',
        ]);

        return;
    }
    throw $e;
}

Prevention

Always define MYSQL_DATABASE (and MYSQL_ROOT_PASSWORD) when creating MySQL service databases.
After editing a service's environment, redeploy and run docker exec <c> env | grep MYSQL to confirm.
When overriding service env, merge rather than replace so required variables survive.

When it happens

Trigger: Backing up a service-based MySQL database whose container was started without MYSQL_DATABASE in its environment: custom env overrides dropped it, the service template omitted it, or the variable was set to an empty name.

Common situations: Users override the service's environment and accidentally remove MYSQL_DATABASE; templates/custom compose files that rely only on MYSQL_ROOT_PASSWORD; databases created manually inside the container instead of via the initial env.

Related errors

AI-assisted analysis of coollabsio/coolify@70b9acc424 (2026-08-17). Data as JSON: /api/errors/8ba02fa845d0ce4d. Report an issue: GitHub.