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

YAML form schema must parse to an array

Error message

YAML form schema must parse to an array

What it means

After yaml_parse()/yaml_parse_file() succeeds, YamlLoader requires the parsed document to be a PHP array; the resulting definitions are handed to ArrayLoader. A YAML root that parses to a scalar (a lone string/number), an empty document (null), or any non-array triggers YamlSchemaNotArray.

Source

Thrown at phalcon/Forms/Loader/YamlLoader.zep:65

     */
    public function load() -> array
    {
        var definitions, loader, source;

        if !this->phpExtensionLoaded("yaml") {
            throw new YamlExtensionRequired();
        }

        let source = this->source;

        if is_file(source) && is_readable(source) {
            let definitions = yaml_parse_file(source);
        } else {
            let definitions = yaml_parse(source);
        }

        if typeof definitions !== "array" {
            throw new YamlSchemaNotArray();
        }

        let loader = new ArrayLoader(definitions);

        return loader->load();
    }
}

View on GitHub (pinned to b7419de9cd)

Solutions

1. Make the YAML root a list of mappings — entries start with '- '
2. Verify the shape before loading: $parsed = yaml_parse_file($path); ensure is_array($parsed)
3. If the file is intentionally empty, skip loading rather than passing it to YamlLoader

Example fix

# before — forms.yaml
version: 2
fields:
  - type: text
    name: email

# after — forms.yaml
- type: text
  name: email
- type: submit
  name: send

if (!extension_loaded('yaml')) {
    throw new \RuntimeException('pecl/yaml extension required');
}

$parsed = is_file($source) && is_readable($source)
    ? yaml_parse_file($source)
    : yaml_parse($source);

if (!is_array($parsed)) {
    throw new \InvalidArgumentException(
        'YAML form schema must be a list of mappings; root parsed to ' . gettype($parsed)
    );
}

/** @param mixed $parsed */
function isYamlDefinitionList($parsed): bool
{
    return is_array($parsed);
}

try {
    $defs = (new \Phalcon\Forms\Loader\YamlLoader($source))->load();
} catch (\Phalcon\Forms\Exceptions\YamlSchemaNotArray $e) {
    // root is a scalar/empty document; fix or skip the file
    $logger->warning('Skipping malformed YAML schema: ' . $e->getMessage());
    $defs = [];
}

When it happens

Trigger: A YAML file containing only a scalar or only comments (parses to null); a root-level mapping (key: value) instead of a list of entries; a file whose list items were accidentally dedented.

Common situations: Empty or fully commented-out schema files left after refactoring; copying YAML from documentation where the root is a mapping; truncation during a deploy.

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

• JSON form schema must decode to an array
• Unknown form element type "{type}"
• 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

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