laravel/framework · error · InvalidArgumentException

Configuration value for key [%s] must be a boolean, %s given

Error message

Configuration value for key [%s] must be a boolean, %s given.

What it means

Thrown by Repository::boolean() (src/Illuminate/Config/Repository.php:161) when the resolved value is not a real bool. is_bool() is strict: the strings "true"/"false", 1/0, or null from env all fail.

Source

Thrown at src/Illuminate/Config/Repository.php:161

        return $value;
    }

    /**
     * Get the specified boolean configuration value.
     *
     * @param  string  $key
     * @param  (\Closure():(bool|null))|bool|null  $default
     * @return bool
     *
     * @throws \InvalidArgumentException
     */
    public function boolean(string $key, $default = null): bool
    {
        $value = $this->get($key, $default);

        if (! is_bool($value)) {
            throw new InvalidArgumentException(
                sprintf('Configuration value for key [%s] must be a boolean, %s given.', $key, gettype($value))
            );
        }

        return $value;
    }

    /**
     * Get the specified array configuration value.
     *
     * @param  string  $key
     * @param  (\Closure():(array<array-key, mixed>|null))|array<array-key, mixed>|null  $default
     * @return array<array-key, mixed>
     *
     * @throws \InvalidArgumentException
     */
    public function array(string $key, $default = null): array
    {

View on GitHub (pinned to bd6b5437e6)

Solutions

  1. Cast explicitly in the config file: 'debug' => filter_var(env('APP_DEBUG', false), FILTER_VALIDATE_BOOLEAN),.
  2. Provide a bool default at call site: config()->boolean('app.debug', false).
  3. After changing .env, run php artisan config:clear then config:cache so env casts are re-evaluated.
  4. Avoid mixing integer 1/0 semantics with the boolean accessor.

Example fix

// before
// 'debug' => env('APP_DEBUG'),  // getenv returns string
config()->boolean('app.debug');

// after
// 'debug' => filter_var(env('APP_DEBUG', false), FILTER_VALIDATE_BOOLEAN),
config()->boolean('app.debug', false);
Defensive patterns

Strategy: validation

Validate before calling

$v = config('app.debug');
if (! is_bool($v)) {
    // fix config source; strings 'true'/'1' will fail
}

Type guard

function isBoolConfig(\Illuminate\Config\Repository $c, string $key): bool
{
    return is_bool($c->get($key));
}

Try / catch

try {
    $debug = config()->boolean('app.debug', false);
} catch (\InvalidArgumentException $e) {
    $debug = false;
}

Prevention

When it happens

Trigger: Calling config()->boolean('app.debug') when the value is the env string "true", an integer 1, or null. The classic trap is env('APP_DEBUG') returning "true" (string) rather than true (bool).

Common situations: Laravel's env loader casts a handful of literal strings, but only when the value comes through env() without a cached config. After config:cache, raw getenv() strings can persist. Also a problem for boolean env values that a user sets as 1/0 in .env.

Related errors

AI-assisted analysis of laravel/framework@bd6b5437e6 (2026-08-06). Data as JSON: /data/errors/3298ca42eed71d65.json. Report an issue: GitHub.