passbolt/passbolt_api · error

If you are using composer run

Error message

If you are using composer run

What it means

This is not an exception but a styled CLI error line printed by ConsoleCommand::execute() when the interactive console cannot start because the Psy\Shell class (psy/psysh package) is not autoloadable. The library checks class_exists('Psy\Shell') and, on failure, prints a multi-line diagnostic block guiding the developer to install psysh via composer. It exists to fail fast with actionable guidance instead of a fatal class-not-found error.

Solutions

1. Run composer to install psysh: composer require psy/psysh (or composer install if it is already in composer.json dev requirements).
2. If running in production, verify this is intentional — the console shell should usually not be used there; remove it from deployment scripts.
3. Check vendor/ exists and vendor/autoload.php includes the class: php -r "var_dump(class_exists('Psy\\Shell'));"
4. Clear composer autoload caches: composer dump-autoload.

Example fix

// before (terminal)
$ bin/cake console
Unable to load Psy\Shell.

// after
$ composer require --dev psy/psysh
$ bin/cake console
You can exit with `CTRL-C` or `exit`

// shell script guard before invoking the console
if php -r "exit(class_exists('Psy\\Shell') ? 0 : 1);"; then
  bin/cake console
else
  echo "psysh missing; run: composer require psy/psysh" >&2
fi

When it happens

Trigger: Running the console command (bin/cake console) in an environment where the psy/psysh composer package is absent — e.g. a production deployment without dev dependencies, or composer install with --no-dev.

Common situations: Deploying passbolt to production where require-dev packages (psysh is typically a dev dependency) are skipped; running the shell inside a minimal Docker image; forgetting to run composer install after cloning; a broken vendor/ autoloader.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

• $ php composer.phar require psy/psysh</info>
• and that Psy\Shell is registered in your autoloader.
• Unable to load Psy\Shell.</error>
• Make sure you have installed psysh as a dependency,
• This is not a valid answer. Please choose Y or n.

AI-assisted analysis of passbolt/passbolt_api@31c1bbc10f (2026-09-17). Data as JSON: /api/errors/c0472250a08bd014. Report an issue: GitHub.

Appendix: source

Thrown at src/Command/ConsoleCommand.php:47

 */
class ConsoleCommand extends Command
{
    /**
     * Start the Command and interactive console.
     *
     * @param \Cake\Console\Arguments $args The command arguments.
     * @param \Cake\Console\ConsoleIo $io The console io
     * @return int|null|void The exit code or null for success
     */
    public function execute(Arguments $args, ConsoleIo $io) // phpcs:ignore
    {
        if (!class_exists('Psy\Shell')) {
            $io->err('<error>Unable to load Psy\Shell.</error>');
            $io->err('');
            $io->err('Make sure you have installed psysh as a dependency,');
            $io->err('and that Psy\Shell is registered in your autoloader.');
            $io->err('');
            $io->err('If you are using composer run');
            $io->err('');
            $io->err('<info>$ php composer.phar require psy/psysh</info>');
            $io->err('');

            return static::CODE_ERROR;
        }

        $io->out('You can exit with <info>`CTRL-C`</info> or <info>`exit`</info>');
        $io->out();

        Log::drop('debug');
        Log::drop('error');
        $io->setLoggers(false);
        restore_error_handler();
        restore_exception_handler();

        $psy = new PsyShell(new PsyConfiguration([
            'updateCheck' => 'never',

View on GitHub (pinned to 31c1bbc10f)