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

Argument ` ` is not defined on this Command. Could this be…

Error message

Argument `%s` is not defined on this Command. Could this be an option maybe?

What it means

Arguments::assertArgumentExists() throws ConsoleException when the requested positional argument name is not defined on the command, hinting the user may have meant an option instead. It is the existence check run at the top of getArgument() and getArrayArgument().

Solutions

Fix the argument name to match one defined on the command
If it is actually an option, use getOption()/getArrayOption()/getBooleanOption() instead
List defined arguments (e.g. via the command's help or definition code) to confirm exact names

Example fix

// before
$opt = $args->getArgument('--verbose');
// after
$opt = $args->getBooleanOption('verbose');

Defensive patterns

Strategy: validation

Validate before calling

// check defined argument names before accessing
if (!in_array($name, $knownArgNames, true)) {
    throw new \InvalidArgumentException("Unknown argument '$name' — defined args: " . implode(', ', $knownArgNames));
}

Type guard

function argOrOption(\Cake\Console\Arguments $a, string $name): string|bool|array|null {
    return $a->hasArgument($name) // if exposed
        ? $a->getArgument($name)
        : $a->getOption($name);
}

Try / catch

try {
    $value = $args->getArgument('target');
} catch (\Cake\Console\Exception\ConsoleException $e) {
    // maybe it's an option
    $value = $args->getOption('target');
}

Prevention

Copy argument names from the command's definition, never from memory
Rename-safe: define argument name constants and reuse them in accessors
Run `bin/app mycommand --help` to see the exact declared argument names

When it happens

Trigger: Calling getArgument('foo') or getArrayArgument('foo') where 'foo' is not in $this->argNames — a typo, or reading an option with an argument getter.

Common situations: Typos in argument names; confusing arguments with options (e.g. --verbose read via getArgument); renaming an argument without updating the accessor; command class reused across commands with different argument sets.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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

Appendix: source

Thrown at src/Console/Arguments.php:300

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

    /**
     * @param string $name
     * @return void
     */
    protected function assertArgumentExists(string $name): void
    {
        if (in_array($name, $this->argNames, true)) {
            return;
        }

        throw new ConsoleException(sprintf(
            'Argument `%s` is not defined on this Command. Could this be an option maybe?',
            $name,
        ));
    }
}

View on GitHub (pinned to 1128eba9b0)