cakephp/cakephp · error · Cake\Console\Exception\ConsoleException

Option ` ` is not of type `array`, use `getOption()`…

Error message

Option `%s` is not of type `array`, use `getOption()` instead.

What it means

Arguments::getArrayOption() returns a repeatable option as ?array. If the option's stored value is a scalar string or bool rather than an array, it throws ConsoleException and tells you to use getOption().

Solutions

1. Use getOption($name) for single-occurrence options
2. Ensure callers actually repeat the option if array semantics are intended
3. Normalize: $opt = is_array($raw) ? $raw : ($raw === null ? null : [$raw]);

Example fix

// before
$env = $args->getArrayOption('env');
// after
$env = $args->getOption('env');

$raw = $args->getOption('env');
if (is_array($raw)) { $env = $args->getArrayOption('env'); } else { $env = $raw === null ? null : [$raw]; }

function expectArrayOption(\Cake\Console\Arguments $a, string $name): ?array {
    $v = $a->getArrayOption($name);
    if ($v !== null && !is_array($v)) { throw new \LogicException("'$name' is not repeatable; use getOption()"); }
    return $v;
}

try {
    $values = $args->getArrayOption('env');
} catch (\Cake\Console\Exception\ConsoleException $e) {
    $one = $args->getOption('env');
    $values = $one === null ? null : [$one];
}

When it happens

Trigger: Calling getArrayOption('opt') when $this->options['opt'] is a string (single occurrence as value option) or bool (bare flag), i.e. the option was not given multiple values.

Common situations: Using the array getter for an option typically passed once (--env=prod); tests or commands where the option appears only once; confusion between flag/value/repeatable option kinds.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Cannot get multiple values for option
• Option ` ` is not of type `bool`, use `getOption()` instead.
• Argument ` ` is not of type `array`, use `getArgument()`…
• Argument ` ` is not of type `string`, use…
• A non-empty `$prefix` is required so discovered commands…

AI-assisted analysis of cakephp/cakephp@1128eba9b0 (2026-09-12). Data as JSON: /api/errors/ef5fe6911f1b2c52. Report an issue: GitHub.

Appendix: source

Thrown at src/Console/Arguments.php:270

    {
        deprecationWarning(
            '5.2.0',
            'getMultipleOption() is deprecated. Use `getArrayOption()` instead.',
        );

        return $this->getArrayOption($name);
    }

    /**
     * Gets a multiple (array) option's value or null if not set.
     *
     * @return array<string>|null
     */
    public function getArrayOption(string $name): ?array
    {
        $value = $this->options[$name] ?? null;
        if ($value !== null && !is_array($value)) {
            throw new ConsoleException(sprintf(
                'Option `%s` is not of type `array`, use `getOption()` instead.',
                $name,
            ));
        }

        return $value;
    }

    /**
     * Check if an option is defined and not null.
     *
     * @param string $name The name of the option to check.
     * @return bool
     */
    public function hasOption(string $name): bool
    {
        return isset($this->options[$name]);
    }

View on GitHub (pinned to 1128eba9b0)