phalcon/cphalcon · error · Phalcon\Auth\Exceptions\FileNotValidJson

Stream adapter file is not valid JSON: {path}

Error message

Stream adapter file is not valid JSON: {path}

What it means

The Auth Stream adapter decodes its users file with Phalcon's Json Decode helper; if that throws InvalidArgumentException the adapter wraps it in FileNotValidJson (chaining the original exception) with the file path. The file exists and is readable, but its contents are not syntactically valid JSON.

Source

Thrown at phalcon/Auth/Adapter/Stream.zep:85

    {
        var contents, data, ex, path, rows;

        let path = this->config->getFile();

        if (!this->phpFileExists(path)) {
            throw new FileDoesNotExist(path);
        }

        let contents = this->phpFileGetContents(path);

        if (contents === false) {
            throw new FileCannotRead(path);
        }

        try {
            let data = (new Decode())->__invoke(contents, true);
        } catch InvalidArgumentException, ex {
            throw new FileNotValidJson(path, ex);
        }

        if (typeof data !== "array") {
            throw new FileDoesNotContainJson(path);
        }

        /** @var list<AuthUserRow> $rows */
        let rows = array_values(data);

        return rows;
    }
}

View on GitHub (pinned to b7419de9cd)

Solutions

1. Validate and locate the error: `php -r 'json_decode(file_get_contents($path), true); echo json_last_error_msg();'`
2. Fix the JSON: double quotes, no comments/trailing commas, no BOM; wrap strings in quotes
3. Seed empty stores with a literal `[]` rather than an empty file
4. Use `jsonlint` or editor JSON validation before committing changes to the file

Example fix

// before (storage/users.json)
{
    // administrators
    'admin': { 'password': '...', },
}
// after
[
    {"username": "admin", "password": "$2y$10$..."}
]

$raw = file_get_contents($config->getFile());
json_decode((string) $raw, true);
if (json_last_error() !== JSON_ERROR_NONE) {
    throw new RuntimeException('Users file is not valid JSON: ' . json_last_error_msg());
}
$adapter = new \Phalcon\Auth\Adapter\Stream($hasher, $config);

try {
    $guard->attempt($credentials);
} catch (\Phalcon\Auth\Exceptions\FileNotValidJson $e) {
    $logger->critical('Auth users file failed JSON validation: ' . $e->getMessage());
    $previous = $e->getPrevious(); // original decode exception with offset details
    throw new RuntimeException('Authentication store corrupt', 0, $e);
}

When it happens

Trigger: First authentication attempt against a users file containing JSON syntax errors: comments, trailing commas, single-quoted strings, unquoted keys, a BOM, or hand-editing mistakes. Decoding is associative (second arg true), but the failure here is parse-level, not shape-level.

Common situations: Manually editing the users file to add a user and breaking syntax; generators emitting JSON5-style output; files saved with a UTF-8 BOM by editors; an empty file is valid only if it contains a valid value — a totally empty string fails.

Related errors

• Stream adapter file does not contain a JSON array: {path}
• Stream adapter file does not exist: {path}
• Malformed ACL snapshot structure
• Stream adapter cannot read file: {path}
• Session guard 'name' and 'rememberName' must differ

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