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

JSON form schema is invalid: {detail}

Error message

JSON form schema is invalid: {detail}

What it means

JsonLoader::load() decodes its source (a JSON string or a readable file path) with JSON_THROW_ON_ERROR; any decode failure is caught and rethrown as InvalidJsonSchema carrying the underlying json error message. This surfaces malformed JSON, truncated files, and bogus input early instead of silently producing an empty form.

Source

Thrown at phalcon/Forms/Loader/JsonLoader.zep:61

    /**
     * @phpstan-return array<int, array<string, mixed>>
     * @throws Exception
     */
    public function load() -> array
    {
        var ex, definitions, json, loader;

        let json = this->source;

        if is_file(json) && is_readable(json) {
            let json = (string) this->phpFileGetContents(json);
        }

        try {
            let definitions = (new Decode())->__invoke(json, true, 512, JSON_THROW_ON_ERROR);
        } catch InvalidArgumentException, ex {
            throw new InvalidJsonSchema(ex->getMessage());
        }

        if typeof definitions !== "array" || !array_is_list(definitions) {
            throw new JsonSchemaNotArray();
        }

        let loader = new ArrayLoader(definitions);

        return loader->load();
    }
}

View on GitHub (pinned to b7419de9cd)

Solutions

1. Pre-validate the document: json_decode($json, true, 512, JSON_THROW_ON_ERROR) before constructing JsonLoader
2. When passing a path, verify is_file($path) && is_readable($path) first
3. Read the exception message — it contains the exact json_last_error detail such as 'Syntax error' with byte offset

Example fix

// before
$loader = new JsonLoader('/config/forms.json'); // path may not exist or contain invalid JSON
$defs = $loader->load();

// after
$path = '/config/forms.json';
if (!is_file($path) || !is_readable($path)) {
    throw new RuntimeException("Schema file missing: {$path}");
}
json_decode((string) file_get_contents($path), true, 512, JSON_THROW_ON_ERROR); // fail fast with a clear error
$defs = (new JsonLoader($path))->load();

$json = is_file($source) && is_readable($source)
    ? (string) file_get_contents($source)
    : $source;

// fail fast with the exact JSON error before the loader sees it
json_decode($json, true, 512, JSON_THROW_ON_ERROR);

$defs = (new \Phalcon\Forms\Loader\JsonLoader($source))->load();

try {
    $defs = (new \Phalcon\Forms\Loader\JsonLoader($source))->load();
} catch (\Phalcon\Forms\Exceptions\InvalidJsonSchema $e) {
    // e->getMessage() carries the underlying json_last_error detail
    $logger->error('Invalid JSON form schema: ' . $e->getMessage());
    throw new \RuntimeException('Form schema is broken; contact the site admin', 0, $e);
}

When it happens

Trigger: Passing a file path that does not exist or is not readable, so the loader tries to decode the path string itself as JSON; hand-edited schema files with trailing commas, single quotes, or unquoted keys; passing YAML or a PHP-exported string by mistake.

Common situations: Schema files edited manually and left with a syntax error; deployment missing the schema file so the literal path is decoded; permissions blocking is_readable(); empty string input.

Related errors

• Form schema definition at index {index} must be an array
• JSON form schema must decode to an array
• Unknown form element type "{type}"
• 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/bd3d1bd29226ebf8. Report an issue: GitHub.