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

Form schema definition at index {index} is missing required

Error message

Form schema definition at index {index} is missing required key "name"

What it means

ArrayLoader::validateDefinition() requires every definition array to carry a non-empty 'name' key, which becomes the element's name inside the form. A definition missing 'name', or with an empty/falsy value, throws SchemaEntryMissingKey reporting the index and the key 'name'.

Source

Thrown at phalcon/Forms/Loader/ArrayLoader.zep:68

    /**
     * @param mixed $definition
     * @param int   $index
     *
     * @throws Exception
     */
    protected function validateDefinition(var definition, int index) -> void
    {
        if typeof definition !== "array" {
            throw new SchemaEntryNotArray(index);
        }

        if !isset definition["type"] || empty definition["type"] {
            throw new SchemaEntryMissingKey(index, "type");
        }

        if !isset definition["name"] || empty definition["name"] {
            throw new SchemaEntryMissingKey(index, "name");
        }
    }
}

View on GitHub (pinned to b7419de9cd)

Solutions

1. Add a non-empty 'name' key to the entry at the reported index, e.g. ['type' => 'text', 'name' => 'email']
2. When generating definitions, guard with isset($def['name']) && $def['name'] !== ''
3. Use the index in the exception message to locate the exact offending entry

Example fix

// before
[
  ['type' => 'text']
]

// after
[
  ['type' => 'text', 'name' => 'email']
]

foreach ($definitions as $index => $definition) {
    if (!isset($definition['name']) || $definition['name'] === '') {
        throw new \InvalidArgumentException(
            "Schema entry {$index} is missing a non-empty 'name'"
        );
    }
}

$defs = (new \Phalcon\Forms\Loader\ArrayLoader($definitions))->load();

function hasValidName(array $definition): bool
{
    return isset($definition['name'])
        && is_string($definition['name'])
        && $definition['name'] !== '';
}

try {
    $defs = (new \Phalcon\Forms\Loader\ArrayLoader($definitions))->load();
} catch (\Phalcon\Forms\Exceptions\SchemaEntryMissingKey $e) {
    // message names index and key ('name'); fix the file at that index
    $logger->error($e->getMessage());
    throw $e;
}

When it happens

Trigger: A schema entry like ['type' => 'text'] with no 'name' key; an entry with 'name' => '' (empty string is rejected by the empty() check); a typo such as 'label' used where 'name' was intended.

Common situations: Copy-pasted schema blocks where the name line was dropped; dynamically generated definitions whose name variable is empty for some rows.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Form schema definition at index {index} is missing required
• Form schema definition at index {index} must be an array
• Unknown form element type "{type}"
• 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/29c02a87c1d61e37. Report an issue: GitHub.