appwrite/appwrite · error · Exception

Invalid environment variable name: {$key}

Error message

Invalid environment variable name: {$key}

What it means

Error "Invalid environment variable name: {$key}" thrown in appwrite/appwrite.

Source

Thrown at src/Appwrite/Platform/Tasks/Install.php:1158

                if (@copy($source, $target) === false) {
                    $lastError = error_get_last();
                    $errorMsg = $lastError ? $lastError['message'] : 'Unknown error';
                    throw new \RuntimeException('Failed to copy ' . $file . ' to ' . $target . ': ' . $errorMsg);
                }
            }
        }
    }

    protected function runDockerCompose(array $input, bool $isLocalInstall, bool $useExistingConfig, bool $isCLI, ?callable $progress = null, bool $isUpgrade = false): void
    {
        $env = '';
        if (!$useExistingConfig) {
            foreach ($input as $key => $value) {
                if ($value === null || $value === '') {
                    continue;
                }
                if (!preg_match(self::PATTERN_ENV_VAR_NAME, $key)) {
                    throw new \Exception("Invalid environment variable name: $key");
                }
                $env .= $key . '=' . \escapeshellarg((string) $value) . ' ';
            }
        }

        if ($isCLI) {
            Console::log("Running \"docker compose up -d --remove-orphans --renew-anon-volumes\"");
        }

        $composePath = $this->path;
        if ($isLocalInstall && $this->hostPath !== '') {
            $composePath = $this->hostPath;
        }
        $composeFile = $composePath . '/' . $this->getComposeFileName();
        $envFile = $composePath . '/' . $this->getEnvFileName();

        $command = [
            'docker',

View on GitHub (pinned to a1d520eea4)

Solutions

1. Rename the environment variable to match the valid pattern: uppercase letters, digits, and underscores, not starting with a digit.
2. Remove or quote any special characters in the variable name and re-run the installer.

When it happens

Trigger: Thrown at src/Appwrite/Platform/Tasks/Install.php:1158 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of appwrite/appwrite@a1d520eea4 (2026-08-18). Data as JSON: /api/errors/6fc96eaeb429c010. Report an issue: GitHub.