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

'prefix' must be a string

Error message

'prefix' must be a string

What it means

The Volt 'prefix' option — a string prepended to compiled template names, used to avoid collisions between compiled files of different apps sharing one cache dir — must be a string; any other type throws InvalidOptionType('prefix', 'string') at phalcon/Mvc/View/Engine/Volt/Compiler.zep:355. It defaults to '' when omitted.

Source

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

                );
            } 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"] {
            if fetch compiledPath, options["compiledPath"] {
                trigger_error(
                    "The 'compiledPath' option is deprecated. Use 'path' instead.",
                    E_USER_DEPRECATED
                );
            } else {
                let compiledPath = "";
            }
        }

        /**

View on GitHub (pinned to b7419de9cd)

Solutions

1. Cast to string: 'prefix' => (string) $tenantId
2. Omit the key entirely when no prefix is needed (default '')
3. Validate the whole options array shape once in your Volt factory

Example fix

// before
$volt->setOptions(['prefix' => $tenant->id]); // int

// after
$volt->setOptions(['prefix' => (string) $tenant->id]);

if (isset($options['prefix']) && !is_string($options['prefix'])) {
    $options['prefix'] = (string) $options['prefix'];
}

function isVoltPrefixValid(mixed $prefix): bool
{
    return !isset($prefix) || is_string($prefix);
}

When it happens

Trigger: setOptions(['prefix' => 0]) or null from a missing config key; a numeric prefix (e.g. tenant ID) passed uncast: ['prefix' => $tenant->id]; array passed by accident.

Common situations: Multi-tenant setups keying compiled templates by tenant with an int ID; INI/JSON config parsing numbers as ints/floats; copying options arrays between projects with changed shapes.

Related errors

• 'always' must be a bool value
• '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/0a3c32819399ba75. Report an issue: GitHub.