phalcon/cphalcon · error · Phalcon\Mvc\Model\Exceptions\StaticMethodRequiresOneArgument

The static method '{method}' in '{className}' requires one a

Error message

The static method '{method}' in '{className}' requires one argument

What it means

Thrown by Model::invokeFinder() (phalcon/Mvc/Model.zep:5068), the engine behind magic static finders: a method like findFirstBy..., findBy... or countBy... was called with an empty argument list. The exception class is Phalcon\Mvc\Model\Exceptions\StaticMethodRequiresOneArgument. The first argument is the value bound to the WHERE condition, so it cannot be omitted.

Source

Thrown at phalcon/Mvc/Model.zep:5068

        /**
         * Check if the method starts with "count"
         */
        elseif starts_with(method, "countBy") {
            let type = "count",
                extraMethod = substr(method, 7);
        }

        /**
         * The called class is the model
         */
        let modelName = get_called_class();

        if !extraMethod {
            return false;
        }

        if unlikely !array_key_exists(0, arguments) {
            throw new StaticMethodRequiresOneArgument(method, get_called_class());
        }

        let model    = create_instance(modelName),
            metaData = model->getModelsMetaData();

        /**
         * Get the attributes
         */
        let attributes = metaData->getReverseColumnMap(model);

        if typeof attributes !== "array" {
            let attributes = metaData->getDataTypes(model);
        }

        /**
         * Check if the extra-method is an attribute
         */
        if isset attributes[extraMethod] {

View on GitHub (pinned to b7419de9cd)

Solutions

Pass the value as the first argument: Invoices::findFirstByStatus('pending')
For dynamic calls, check the arguments array is non-empty before invoking
Pass null explicitly to search for NULL: Invoices::findFirstByStatus(null) generates IS NULL

Example fix

// before
$invoice = Invoices::findFirstByStatus(); // StaticMethodRequiresOneArgument

// after
$invoice = Invoices::findFirstByStatus('pending');
// or for NULL lookup:
$invoice = Invoices::findFirstByStatus(null);

Defensive patterns

Strategy: type-guard

Validate before calling

if (func_num_args() < 1) {
    throw new InvalidArgumentException('finder value required');
}
$value = $args[0] ?? null;
$invoice = Invoices::findFirstByStatus($value);

Type guard

// guard before a dynamically built magic finder call
function assertFinderArgs(string $method, array $args): void
{
    if (preg_match('/^(findFirstBy|findBy|countBy)/', $method) && !array_key_exists(0, $args)) {
        throw new InvalidArgumentException("{$method} requires one argument");
    }
}

Try / catch

try {
    $invoice = Invoices::findFirstByStatus($status);
} catch (\Phalcon\Mvc\Model\Exceptions\StaticMethodRequiresOneArgument $e) {
    // programming error: default the value and log it
    $status = $status ?? 'pending';
    $invoice = Invoices::findFirstByStatus($status);
}

Prevention

Always pass the value, even null, when you want an IS NULL lookup
Static-analyze call sites: magic finders with zero args are detectable with custom PHPStan rules
Prefer explicit find(['conditions' => ...]) for dynamic code paths

When it happens

Trigger: Calling Invoices::findFirstByStatus() with no parameters; forwarding a finder call with call_user_func_array([Invoices::class, 'findByStatus']) and an empty array; refactoring a method signature and dropping the argument at the call site.

Common situations: Refactor typos where the value variable is removed; dynamic finder invocation from user input where the parameter key is missing; copy-pasted example code without arguments.

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 phalcon/cphalcon@b7419de9cd (2026-08-21). Data as JSON: /api/errors/cdfcdc8d1227f03e. Report an issue: GitHub.