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

Stream adapter file does not exist: {path}

Error message

Stream adapter file does not exist: {path}

What it means

The Auth Stream adapter keeps its user store in a JSON file whose path comes from StreamAdapterConfig. On the first authentication attempt it lazily loads users and starts by checking file existence; a missing file yields FileDoesNotExist with the configured path, before any read or JSON parsing happens.

Source

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

        );
    }

    /**
     * Loads and decodes the JSON users file. Re-read on every call - if you
     * need caching, wrap it.
     *
     * @phpstan-return list<AuthUserRow>
     *
     * @throws Exception
     */
    protected function loadUsers() -> array
    {
        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);
        }

View on GitHub (pinned to b7419de9cd)

Solutions

1. Create the users file at the exact path shown in the message and seed it with a JSON array
2. Use an absolute path (or one built from a known base constant) so resolution does not depend on CWD
3. Add the file to your deployment/seed scripts and .gitignore policy as appropriate

Example fix

// before
$adapter = new \Phalcon\Auth\Adapter\Stream($hasher, new StreamAdapterConfig(['file' => 'storage/users.json']));
// after
$file = dirname(__DIR__) . '/storage/users.json';
if (!is_file($file)) {
    file_put_contents($file, "[]"); // or ship a seeded users file
}
$adapter = new \Phalcon\Auth\Adapter\Stream($hasher, new StreamAdapterConfig(['file' => $file]));

$file = $config->getFile();
if (!is_file($file)) {
    throw new RuntimeException('Auth users file missing: ' . $file);
}
$adapter = new \Phalcon\Auth\Adapter\Stream($hasher, $config);

try {
    $guard->attempt($credentials);
} catch (\Phalcon\Auth\Exceptions\FileDoesNotExist $e) {
    $logger->critical('Auth users file missing: ' . $e->getMessage());
    throw new RuntimeException('Authentication store unavailable', 0, $e);
}

When it happens

Trigger: Authenticating via the Stream adapter when config->getFile() points to a path that does not exist: wrong filename, relative path resolved against a different working directory, or the file simply never deployed.

Common situations: Relative paths breaking between web and CLI entry points; environment-specific users file omitted from deployment; typo in the config key; fresh clone without the seed file.

Related errors

• Stream adapter file is not valid JSON: {path}
• Stream adapter file does not contain a JSON array: {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/8be6293a3b766c3b. Report an issue: GitHub.