What causes "Stream adapter file does not exist: {path}" in phalcon/cphalcon?

Create the users file at the exact path shown in the message and seed it with a JSON array

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

Stream adapter file does not exist

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.

Solutions

Create the users file at the exact path shown in the message and seed it with a JSON array
Use an absolute path (or one built from a known base constant) so resolution does not depend on CWD
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]));

Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

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);
}

Prevention

Use absolute paths for the users file built from a known base constant
Include/seed the users file in deployment scripts and verify presence in a health check
Fail a startup probe if the configured auth file is absent

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.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

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

Appendix: 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)