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

Unknown form element type "{type}"

Error message

Unknown form element type "{type}"

What it means

Thrown by Phalcon\Forms\FormsLocator::getElement() when the element type string is not present in the element factory registry. The locator seeds default types ('text', 'email', 'select', 'textarea', ...) used by Form::load() to build elements from a schema; any type outside that map — including a wrongly capitalized one — is rejected because no factory exists for it.

Source

Thrown at phalcon/Forms/FormsLocator.zep:125

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

        return instance;
    }

    /**
     * Returns the factory callable for the given element type.
     *
     * @param string $type
     *
     * @return callable
     * @throws Exception
     */
    public function getElement(string type)
    {
        if !isset this->elements[type] {
            throw new UnknownFormElementType(type);
        }

        return this->elements[type];
    }

    /**
     * Checks whether a named form factory is registered.
     *
     * @param string $name
     *
     * @return bool
     */
    public function has(string name) -> bool
    {
        return isset this->factories[name];
    }

    /**

View on GitHub (pinned to b7419de9cd)

Solutions

1. Normalize the schema type to lowercase and match a registered key exactly (check, checkgroup, date, email, file, hidden, numeric, password, radio, radiogroup, select, submit, text, textarea)
2. Register custom types before loading the schema: $locator->setElement('colorpicker', fn(string $name, array $options, array $attrs) => new ColorPicker($name, $options, $attrs))
3. Guard with $locator->hasElement($type) before calling getElement()
4. Validate schema types against hasElement() during a build or deploy step

Example fix

// before — schema uses "type": "Text"
[
  { "type": "Text", "name": "email" }
]

// after
[
  { "type": "text", "name": "email" }
]

// or register the custom type
$locator->setElement('colorpicker', fn(string $name, array $options, array $attrs) => new ColorPicker($name, $options, $attrs));

$type = strtolower((string) $definition['type']);

if (!$locator->hasElement($type)) {
    // register it or reject the schema early with a precise message
    throw new \InvalidArgumentException("Unknown element type '{$type}' at index {$index}");
}

$factory = $locator->getElement($type);

/** @param mixed $type */
function isValidElementType(\Phalcon\Forms\FormsLocator $locator, $type): bool
{
    return is_string($type)
        && $type !== ''
        && $locator->hasElement(strtolower($type));
}

try {
    $factory = $locator->getElement($type);
} catch (\Phalcon\Forms\Exceptions\UnknownFormElementType $e) {
    // log the schema type and skip the entry, or fail the whole load
    error_log($e->getMessage());
    continue;
}

When it happens

Trigger: A schema entry with "type": "Text" instead of lowercase "text"; a custom type such as 'colorpicker' referenced by a schema without a prior $locator->setElement('colorpicker', $factory); a typo like 'textara'.

Common situations: Schema-driven forms (ArrayLoader/JsonLoader/YamlLoader via Form::load()) where type strings drift from the registry; adding custom element types but forgetting the setElement() registration; upgrading Phalcon versions where the set of default types changed.

Related errors

• Form schema definition at index {index} must be an array
• Form schema definition at index {index} is missing required
• Form schema definition at index {index} is missing required
• JSON form schema is invalid: {detail}
• JSON form schema must decode to an array

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