phalcon/cphalcon · error · Phalcon\Mvc\View\Engine\Volt\Exceptions\InvalidOptionType

'always' must be a bool value

Error message

'always' must be a bool value

What it means

When parsing Volt compiler options, the 'always' key (or deprecated 'compileAlways') must be a real boolean; anything else triggers InvalidOptionType('always', 'bool value') at phalcon/Mvc/View/Engine/Volt/Compiler.zep:344. This flag forces recompilation of every template on each request — a development-only setting — and a truthy-looking string would silently change compile semantics, hence the strict check.

Source

Thrown at phalcon/Mvc/View/Engine/Volt/Compiler.zep:344

        let options = this->options;

        /**
         * This makes that templates will be compiled always
         */
        if !fetch compileAlways, options["always"] {
            if fetch compileAlways, options["compileAlways"] {
                trigger_error(
                    "The 'compileAlways' option is deprecated. Use 'always' instead.",
                    E_USER_DEPRECATED
                );
            } else {
                let compileAlways = false;
            }
        }

        if unlikely typeof compileAlways != "boolean" {
            throw new InvalidOptionType("always", "bool value");
        }

        /**
         * Prefix is prepended to the template name
         */
        if !fetch prefix, options["prefix"] {
            let prefix = "";
        }

        if unlikely typeof prefix != "string" {
            throw new InvalidOptionType("prefix", "string");
        }

        /**
         * Compiled path is a directory where the compiled templates will be
         * located
         */
        if !fetch compiledPath, options["path"] {

View on GitHub (pinned to b7419de9cd)

Solutions

1. Cast before passing: 'always' => (bool) env('VOLT_COMPILE_ALWAYS', false)
2. Use proper native booleans in the config source (true/false in PHP config, not 'true'/'false')
3. Rename the deprecated 'compileAlways' key to 'always' at the same time to remove the deprecation notice

Example fix

// before
$volt->setOptions(['always' => getenv('APP_DEBUG')]); // '1' string

// after
$volt->setOptions(['always' => (bool) getenv('APP_DEBUG')]);

$options['always'] = (bool) ($options['always'] ?? $options['compileAlways'] ?? false);
unset($options['compileAlways']);

function isVoltOptionsShape(array $options): bool
{
    return !isset($options['always'], $options['compileAlways'])
        || is_bool($options['always'] ?? $options['compileAlways']);
}

When it happens

Trigger: setOptions(['always' => 'true']) or ['always' => '1'] from env vars/JSON/INI config where everything is a string; ['compileAlways' => 1] using the deprecated key with an int; YAML config parsed with string scalars.

Common situations: Reading APP_DEBUG-style env vars into Volt options without casting; Phalcon 4 -> 5 migrations where the old 'compileAlways' spelling now also gets type-checked; config shared across environments with string booleans.

Related errors

• 'prefix' must be a string
• 'separator' must be a string
• 'extension' must be a string
• The extension is not valid
• 'path' closure didn't return a valid string

AI-assisted analysis of phalcon/cphalcon@b7419de9cd (2026-08-21). Data as JSON: /api/errors/410c345b2b85417b. Report an issue: GitHub.