phalcon/cphalcon · error · MissingParameterKey

Service 'className' is required in parameter on position {}

Error message

Service 'className' is required in parameter on position {}

What it means

Thrown by Phalcon\Di\Service\Builder::buildParameter() when an argument is declared with 'type' => 'instance' but has no 'className' key. The 'instance' type asks the builder to construct a new object of that class (optionally with its own 'arguments'); 'className' names the class to instantiate.

Source

Thrown at phalcon/Di/Service/Builder.zep:239

                return container->get(name);

            /**
             * If the argument type is 'parameter', we assign the value as it is
             */
            case "parameter":
                if unlikely !fetch value, argument["value"] {
                    throw new MissingParameterKey("value", position);
                }

                return value;

            /**
             * If the argument type is 'instance', we assign the value as it is
             */
            case "instance":
                if unlikely !fetch name, argument["className"] {
                    throw new MissingParameterKey("className", position);
                }

                if fetch instanceArguments, argument["arguments"] {
                    /**
                     * Build the instance with arguments
                     */
                    return container->get(name, instanceArguments);
                }

                /**
                 * The instance parameter does not have arguments for its
                 * constructor
                 */
                return container->get(name);

            default:
                /**
                 * Unknown parameter type

View on GitHub (pinned to b7419de9cd)

Solutions

1. Add 'className': ['type' => 'instance', 'className' => \App\ValueObject::class, 'arguments' => [...]].
2. If migrating from Phalcon 3, note the key is 'className' (and setter injection entries also changed shape) - run the 4.x/5.x upgrade guide over all array definitions.
3. Ensure the class exists and is autoloadable, otherwise the subsequent container->get() will fail differently.

Example fix

// before
$di->set('handler', [
    'className' => \App\Handler::class,
    'arguments' => [
        [
            'type' => 'instance',
            'arguments' => [['type' => 'parameter', 'value' => 'x']],
        ],
    ],
]);

// after
$di->set('handler', [
    'className' => \App\Handler::class,
    'arguments' => [
        [
            'type' => 'instance',
            'className' => \App\Dependency::class,
            'arguments' => [['type' => 'parameter', 'value' => 'x']],
        ],
    ],
]);

function assertInstanceArgument(array $arg, int $position): void
{
    if (($arg['type'] ?? null) === 'instance'
        && (!isset($arg['className']) || !class_exists($arg['className']))) {
        throw new InvalidArgumentException("Argument {$position}: 'instance' requires an existing 'className'");
    }
}

function isInstantiableArgument(mixed $arg): bool
{
    return is_array($arg)
        && ($arg['type'] ?? null) === 'instance'
        && isset($arg['className'])
        && class_exists($arg['className']);
}

try {
    $handler = $di->get('requestHandler');
} catch (\Phalcon\Di\Exceptions\MissingParameterKey $e) {
    // message ends with ... 'className' is required ... - fix the definition
    $logger->error('DI definition error: ' . $e->getMessage());
    throw $e;
}

When it happens

Trigger: An argument entry like ['type' => 'instance', 'arguments' => [...]] without 'className', thrown when the owning service is resolved. Message reads: "Service 'className' is required in parameter on position N".

Common situations: Migrating from Phalcon 3.x where the same shape used 'type' => 'class', or hand-writing nested instance definitions and forgetting the class name. Also appears when className comes from a config value that is null/absent in some environment.

Related errors

• Argument at position {} must have a type
• Service '{}' is required in parameter on position {}
• Service 'value' is required in parameter on position {}
• Unknown service type in parameter on position {}
• A dependency injection container is required to access the '

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