{"record":{"id":"25f30310bd67e470","repo":"phalcon/cphalcon","slug":"service-classname-is-required-in-parameter-on-po","errorCode":null,"errorMessage":"Service 'className' is required in parameter on position {}","messagePattern":"Service 'className' is required in parameter on position (.+?)","errorType":"exception","errorClass":"MissingParameterKey","httpStatus":null,"severity":"error","filePath":"phalcon/Di/Service/Builder.zep","lineNumber":239,"sourceCode":"\n                return container->get(name);\n\n            /**\n             * If the argument type is 'parameter', we assign the value as it is\n             */\n            case \"parameter\":\n                if unlikely !fetch value, argument[\"value\"] {\n                    throw new MissingParameterKey(\"value\", position);\n                }\n\n                return value;\n\n            /**\n             * If the argument type is 'instance', we assign the value as it is\n             */\n            case \"instance\":\n                if unlikely !fetch name, argument[\"className\"] {\n                    throw new MissingParameterKey(\"className\", position);\n                }\n\n                if fetch instanceArguments, argument[\"arguments\"] {\n                    /**\n                     * Build the instance with arguments\n                     */\n                    return container->get(name, instanceArguments);\n                }\n\n                /**\n                 * The instance parameter does not have arguments for its\n                 * constructor\n                 */\n                return container->get(name);\n\n            default:\n                /**\n                 * Unknown parameter type","sourceCodeStart":221,"sourceCodeEnd":257,"githubUrl":"https://github.com/phalcon/cphalcon/blob/b7419de9cd0a8a3f48441ead84c9f8415d463e25/phalcon/Di/Service/Builder.zep#L221-L257","documentation":"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.","triggerScenarios":"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\".","commonSituations":"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.","solutions":["Add 'className': ['type' => 'instance', 'className' => \\App\\ValueObject::class, 'arguments' => [...]].","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.","Ensure the class exists and is autoloadable, otherwise the subsequent container->get() will fail differently."],"exampleFix":"// before\n$di->set('handler', [\n    'className' => \\App\\Handler::class,\n    'arguments' => [\n        [\n            'type' => 'instance',\n            'arguments' => [['type' => 'parameter', 'value' => 'x']],\n        ],\n    ],\n]);\n\n// after\n$di->set('handler', [\n    'className' => \\App\\Handler::class,\n    'arguments' => [\n        [\n            'type' => 'instance',\n            'className' => \\App\\Dependency::class,\n            'arguments' => [['type' => 'parameter', 'value' => 'x']],\n        ],\n    ],\n]);","handlingStrategy":"validation","validationCode":"function assertInstanceArgument(array $arg, int $position): void\n{\n    if (($arg['type'] ?? null) === 'instance'\n        && (!isset($arg['className']) || !class_exists($arg['className']))) {\n        throw new InvalidArgumentException(\"Argument {$position}: 'instance' requires an existing 'className'\");\n    }\n}","typeGuard":"function isInstantiableArgument(mixed $arg): bool\n{\n    return is_array($arg)\n        && ($arg['type'] ?? null) === 'instance'\n        && isset($arg['className'])\n        && class_exists($arg['className']);\n}","tryCatchPattern":"try {\n    $handler = $di->get('requestHandler');\n} catch (\\Phalcon\\Di\\Exceptions\\MissingParameterKey $e) {\n    // message ends with ... 'className' is required ... - fix the definition\n    $logger->error('DI definition error: ' . $e->getMessage());\n    throw $e;\n}","preventionTips":["After Phalcon 3 -> 5 upgrades, grep all definitions for 'type' => 'class' and missing 'className' entries in one sweep.","class_exists() at boot also catches autoloading/namespace problems before they become runtime 500s."],"tags":["phalcon","dependency-injection","di","configuration","service-container"],"backgroundTag":"di-definition-invalid","analyzedSha":"b7419de9cd0a8a3f48441ead84c9f8415d463e25","analyzedAt":"2026-08-21T06:21:18.811Z","schemaVersion":2},"datasetVersion":"2026-08-21T11:28:35.574Z"}