What causes "Form '{name}' is not registered in the FormsLocator" in phalcon/cphalcon?

Register the factory before use: $locator->set('login', fn(?object $entity) => new LoginForm($entity))

phalcon/cphalcon · error · Phalcon\Forms\Exceptions\FormNotInLocator

Form '{name}' is not registered in the FormsLocator

Error message

Form '{name}' is not registered in the FormsLocator

What it means

Thrown by Phalcon\Forms\FormsLocator::get() when the requested form name has no registered factory. The locator is a closure registry: each form must be registered with set($name, fn(?object $entity) => new Form) or supplied in the constructor's definitions array before get() can resolve it.

Source

Thrown at phalcon/Forms/FormsLocator.zep:97

    /**
     * Returns the named form.
     *
     * Without an entity the result is lazily created and cached.
     * With an entity a fresh form is always produced.
     *
     * @param string      $name
     * @param object|null $entity
     *
     * @return Form
     * @throws Exception
     */
    public function get(string name, var entity = null) -> <Form>
    {
        var factory, instance;

        if !this->has(name) {
            throw new FormNotInLocator(name);
        }

        let factory = this->factories[name];

        if entity !== null {
            return {factory}(entity);
        }

        if !fetch instance, this->instances[name] {
            let instance = {factory}(null);
            let this->instances[name] = instance;
        }

        return instance;
    }

    /**
     * Returns the factory callable for the given element type.

View on GitHub (pinned to b7419de9cd)

Solutions

Register the factory before use: $locator->set('login', fn(?object $entity) => new LoginForm($entity))
Guard the lookup: if ($locator->has('login')) { $form = $locator->get('login'); }
Compare the exact spelling and case of the name passed to get() against the set() or constructor registration

Example fix

// before
$form = $locator->get('signup'); // never registered

// after
$locator->set('signup', fn(?object $entity = null) => new SignUpForm($entity));
$form = $locator->get('signup');

Defensive patterns

Strategy: validation

Validate before calling

if ($locator->has($name)) {
    $form = $locator->get($name, $entity);
} else {
    throw new \RuntimeException("Form '{$name}' is not registered in the locator");
}

Try / catch

try {
    $form = $locator->get($name, $entity);
} catch (\Phalcon\Forms\Exceptions\FormNotInLocator $e) {
    // fall back to building the form directly
    $form = new DefaultForm($entity);
}

Prevention

Register all form factories in one composition root so registrations cannot be skipped
Add a startup check that iterates your expected form names and asserts $locator->has($name)
Store form registry keys alongside the form classes (config mapping) instead of duplicating strings

When it happens

Trigger: Calling $locator->get('login') before $locator->set('login', ...) was ever called; requesting a form name absent from the definitions array passed to new FormsLoader([$definitions]); a typo or case difference between the set() key and the get() key.

Common situations: A central form registry in the DI container where the new form class was written but never registered; refactoring form names; registration living in a config file that was not updated in one environment.

Related errors

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