composer/composer · error · RuntimeException

Invalid value for {$name}: {$value}. Expected 0, 1, false, t

Error message

Invalid value for {$name}: {$value}. Expected 0, 1, false, true, off, or on.

What it means

Thrown by Platform::getBoolEnv() when an environment variable is set but its value is not one of the strict literals '0', '1', 'false', 'true', 'off', 'on'. The method deliberately rejects fuzzy booleans (yes/no, TRUE with whitespace, 2, quoted values) so config behavior is deterministic. An unset or empty variable does NOT trigger this — it returns the default.

Source

Thrown at src/Composer/Util/Platform.php:106

    /**
     * Read a boolean-style env var. Accepts only the literal strings '0' or '1'.
     *
     * Returns true for '1', false for '0', and $default when the variable is unset.
     * Throws \RuntimeException for any other value (including the empty string).
     *
     * @param non-empty-string $name
     * @return ($default is bool ? bool : ?bool)
     */
    public static function getBoolEnv(string $name, ?bool $default = null): ?bool
    {
        $value = self::getEnv($name);
        if (false === $value || '' === $value) {
            return $default;
        }

        if (!in_array($value, ['0', '1', 'false', 'true', 'off', 'on'], true)) {
            throw new \RuntimeException(
                "Invalid value for {$name}: {$value}. Expected 0, 1, false, true, off, or on."
            );
        }

        return in_array($value, ['1', 'true', 'on', ], true);
    }

    /**
     * Refuses to parse a tar/phar archive on PHP < 8.0, where the \Phar/\PharData
     * constructor handles archive metadata in a way that is unsafe with untrusted
     * input. PHP 8.0+ is not affected, so this is a no-op there.
     *
     * @internal
     * @throws \RuntimeException when run on PHP < 8.0 without the explicit opt-out env var
     */
    public static function assertPharMetadataSafe(): void
    {
        if (\PHP_VERSION_ID >= 80000) {

View on GitHub (pinned to 6ffc117740)

Solutions

1. Set the variable to a literal '1' or '0' (preferred): e.g. export SOME_VAR=1
2. If the flag should be off, unset the variable entirely rather than setting it to 'no'/'off-but-different'
3. Trim whitespace and lowercase the value in your shell wrapper before exporting: export SOME_VAR=$(echo "$SOME_VAR" | tr '[:upper:]' '[:lower:]' | xargs)
4. Audit all COMPOSER_* and library-specific bool vars in your env for values outside the allowed set

Example fix

// before
export COMPOSER_DISABLE_NETWORK=yes   # triggers the error

// after
export COMPOSER_DISABLE_NETWORK=1      # accepted literal

// Validate/normalize the env var BEFORE relying on Platform::getBoolEnv
$raw = getenv('SOME_VAR');
if ($raw !== false && $raw !== '') {
    $normalized = strtolower(trim($raw));
    if (!in_array($normalized, ['0','1','false','true','off','on'], true)) {
        throw new \InvalidArgumentException(
            "SOME_VAR must be one of 0/1/false/true/off/on, got: {$raw}"
        );
    }
}
// now safe to call
$flag = Platform::getBoolEnv('SOME_VAR', false);

// Wrap reads of bool env vars so a bad value degrades gracefully
try {
    $flag = Platform::getBoolEnv('SOME_VAR', false);
} catch (\RuntimeException $e) {
    // log and fall back to default rather than aborting
    error_log($e->getMessage());
    $flag = false;
}

When it happens

Trigger: Calling Platform::getBoolEnv('SOME_VAR') (or any Composer code path that reads a bool env var such as COMPOSER_NO_INTERACTION, COMPOSER_DISABLE_NETWORK, etc.) where SOME_VAR is exported with a value like 'yes', 'no', '2', 'TRUE', ' true ', or 'enable'. The check is case- and whitespace-sensitive.

Common situations: CI config (GitLab/GitHub Actions env:) sets COMPOSER_* flags to 'true' with surrounding quotes or to yes/no; a .env file uses ON/OFF variants the shell leaves verbatim; a Docker ENV statement copies a value with trailing whitespace; migrating from another tool that accepted 'yes'/'no'.

Related errors

• Invalid value for COMPOSER_DISCARD_CHANGES: {env}. Expected
• The COMPOSER environment variable is set to {env} which is a
• The configured cafile was not valid or could not be read.
• The configured capath was not valid or could not be read.
• --abandoned must be one of '.implode(', ', ListPolicyConfig:

AI-assisted analysis of composer/composer@6ffc117740 (2026-08-07). Data as JSON: /api/errors/6b944ce80393de4c. Report an issue: GitHub.