Troubleshooting

This guide covers common problems you might encounter with PsySH and how to resolve them.

Installation Issues

Dependencies not found

Error:

PsySH dependencies not found, be sure to run `composer install`.
See https://getcomposer.org to get Composer.

Cause: PsySH’s dependencies are not installed.Solution:If you cloned the repository:

composer install

If using globally:

composer global require psy/psysh

From bin/psysh:329-332.

Class 'Psy\Shell' not found

Error:

Fatal error: Class 'Psy\Shell' not found

Cause: PsySH is not autoloaded properly.Solution:Ensure you’ve included the Composer autoloader:

require __DIR__ . '/vendor/autoload.php';

Or if installed globally, the psysh binary should handle this automatically.

Cannot download manual

Error:

Downloading manual v3.0... Failed.
Error: Could not download file

Cause: Network connectivity issues or GitHub unavailable.Solutions:

Check internet connection:
```
curl -I https://github.com
```
Check firewall/proxy: Ensure GitHub is not blocked
Try different downloader: PsySH tries cURL, then falls back to file_get_contents
Manual download:
- Download from PsySH releases
- Place in ~/.local/share/psysh/php_manual.php

Runtime Errors

Parse error when entering code

Error:

>>> function test() {
PHP Parse error:  syntax error, unexpected end of file

Cause: Multi-line code requires all lines before execution.Solution: Complete the code block:

>>> function test() {
...   return 'hello';
... }
=> null

Or use semicolons to force execution:

>>> function test() { return 'hello'; }
=> null

Variable not found

Error:

>>> echo $myvar
PHP Notice:  Undefined variable: myvar

Cause: Variable hasn’t been defined in current scope.Solution:List defined variables:

>>> ls
Variables: $_

Define the variable first:

>>> $myvar = 'value'
=> "value"

>>> echo $myvar
value

Fatal error crashes PsySH

Error: PsySH exits completely after a fatal error.Cause: Process forking is disabled or unavailable.Solution: Enable process forking (requires pcntl extension):In .psysh.php:

return [
    'usePcntl' => true,
];

Install pcntl (if not available):

# On Ubuntu/Debian
sudo apt-get install php-pcntl

# On macOS (already included)
# No action needed

# On Windows
# pcntl is not available

Check if available:

>>> extension_loaded('pcntl')
=> true

Infinite loop cannot be stopped

Error: Code is stuck in infinite loop, Ctrl+C doesn’t work.Cause: Signal handling is disabled or unavailable.Solutions:

Force terminate: Press Ctrl+\ (SIGQUIT) or kill from another terminal
Enable pcntl for better signal handling:
```
return [
    'usePcntl' => true,
];
```

Use timeout: Set execution time limit:

>>> set_time_limit(5);
>>> while(true) { sleep(1); }
PHP Fatal error: Maximum execution time of 5 seconds exceeded

Configuration Issues

Config file not loaded

Error: Configuration in .psysh.php is not applied.Cause: Config file is in wrong location or has syntax errors.Solution:

Check file location:

# Should be in one of:
~/.config/psysh/config.php
# or
~/.psysh.php
# or project root
.psysh.php

Verify syntax:
```
php -l ~/.config/psysh/config.php
```

Check return value:

<?php
// Must return an array
return [
    'colorMode' => 'forced',
];

Use PSYSH_CONFIG environment variable:

export PSYSH_CONFIG=/path/to/config.php
psysh

Multiple config files warning

Warning:

Warning: Multiple configuration files found:
  - /home/user/.config/psysh/config.php
  - /home/user/.psysh.php
Using /home/user/.config/psysh/config.php

Cause: PsySH found multiple config files and is warning about which one it’s using.Solution: Remove duplicate config files, keep only one:

# Keep the XDG-compliant location
rm ~/.psysh.php

Or disable the warning:

return [
    'warnOnMultipleConfigs' => false,
];

Invalid configuration option

Error: PsySH ignores unknown configuration options.Cause: Typo or invalid option name.Solution: Check valid options in src/Configuration.php:62-98:

return [
    'colorMode',         // not 'colourMode'
    'configDir',         // not 'configDirectory'
    'historyFile',       // not 'historyPath'
    'manualDbFile',      // not 'manualFile'
    'usePcntl',          // not 'enablePcntl'
    'useTabCompletion',  // not 'tabCompletion'
    // ... etc
];

Autoloading Issues

Project classes not found

Error:

>>> $obj = new App\MyClass
PHP Fatal error: Class 'App\MyClass' not found

Cause: Project autoloader not loaded.Solution:

Trust the project:
```
psysh --trust-project
```

Manually load autoloader:

>>> require 'vendor/autoload.php'
>>> $obj = new App\MyClass
=> App\MyClass {#123}

Check if autoloader exists:
```
ls -la vendor/autoload.php
```
Run composer install if missing:
```
composer install
```

Skipping project autoload warning

Warning:

Skipping project autoload (vendor/autoload.php) in untrusted project ~/project. 
Use --trust-project to allow.

Cause: Project is not in trusted projects list.Solution:Trust the project:

psysh --trust-project

Or configure global trust (not recommended):

return [
    'trustProject' => 'always', // dangerous!
];

See Project Trust for more details.

Local PsySH skipped

Warning:

Skipping local PsySH at ~/project (project is untrusted). 
Re-run with --trust-project to allow.

Cause: Project has local PsySH but is not trusted.Solution:

psysh --trust-project

Or run the local version directly:

./vendor/bin/psysh

Display Issues

No colors in output

Problem: Output is plain text without colors.Causes & Solutions:

Terminal doesn’t support colors:

# Check TERM
echo $TERM
# Should be: xterm-256color, screen-256color, etc.

Force color mode:

return [
    'colorMode' => \Psy\Configuration::COLOR_MODE_FORCED,
];

On Windows: Use Windows Terminal or ConEmu for better color support

Garbled characters or boxes

Problem: Special characters display as boxes or garbage.Cause: Unicode/UTF-8 not supported or enabled.Solution:

Set terminal encoding to UTF-8:

export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8

Disable Unicode in PsySH:
```
return [
    'useUnicode' => false,
];
```

Output too wide for terminal

Problem: Output doesn’t wrap correctly.Solution: PsySH auto-detects terminal width, but you can configure pager:

return [
    'pager' => 'less -R',
];

Or disable pager:

return [
    'pager' => false,
];

Readline Issues

No command history

Problem: Up/down arrows don’t recall previous commands.Cause: Readline extension not available or history disabled.Solution:

Check readline:

>>> extension_loaded('readline')
=> false  // Problem!

Install readline:

# Ubuntu/Debian
sudo apt-get install php-readline

# macOS (Homebrew)
brew install php

Configure history file:

return [
    'historyFile' => '~/.psysh_history',
    'historySize' => 5000,
];

Tab completion not working

Problem: Tab doesn’t complete code.Cause: Tab completion disabled or unsupported.Solution:Enable tab completion:

return [
    'useTabCompletion' => true,
];

Check if working:

>>> array_m<TAB>
array_map        array_merge      array_multisort

Bracketed paste issues

Problem: Pasting code inserts escape sequences.Cause: Bracketed paste mode incompatible with terminal.Solution: Disable bracketed paste:

return [
    'useBracketedPaste' => false,
];

Manual/Documentation Issues

Manual not found

Error:

>>> doc strlen
PHP manual not found.

To document core PHP functionality, download the PHP reference manual:
    doc --update-manual

Solution: Download the manual:

>>> doc --update-manual
Downloading manual v3.0... OK
Installed manual v3.0 to ~/.local/share/psysh/php_manual.php

Invalid manual file

Error:

Invalid manual file detected: ~/.local/share/psysh/php_manual.php

Cause: Manual file is corrupted or wrong format.Solution: Remove and re-download:

>>> doc --update-manual
Remove this file and continue? [Y/n] y
Downloading manual v3.0... OK

Or manually:

rm ~/.local/share/psysh/php_manual.php
psysh
>>> doc --update-manual

Multiple manual files warning

Warning:

Multiple manual database files found: php_manual.php, php_manual.sqlite. 
Using php_manual.php

Cause: Both V2 (SQLite) and V3 (PHP) formats exist.Solution: Remove old SQLite format:

rm ~/.local/share/psysh/php_manual.sqlite

This is informational - PsySH correctly uses the newer format.

Permission Issues

Data directory not writable

Error:

Data directory is not writable.

Cause: No write permission to data directory.Solution:Fix permissions:

chmod u+w ~/.local/share/psysh

Or use custom directory:

return [
    'dataDir' => '/writable/path/psysh-data',
];

Cannot save history

Problem: Command history not persisting between sessions.Cause: History file not writable.Solution:

chmod u+w ~/.config/psysh/psysh_history

Or specify different location:

return [
    'historyFile' => '/tmp/psysh_history',
];

Cannot save trust settings

Warning:

Unable to save trust settings. Trusting /path/to/project for this session only.

Cause: Config directory not writable.Solution:

chmod u+w ~/.config/psysh

Performance Issues

Slow startup time

Problem: PsySH takes several seconds to start.Causes & Solutions:

Large autoload files: Disable autoload warming:

return [
    'warmAutoload' => false,
];

Update checks: Disable automatic updates:

return [
    'updateCheck' => null,
    'updateManualCheck' => null,
];

Too many includes: Reduce default includes:

return [
    'defaultIncludes' => [],
];

Slow tab completion

Problem: Tab completion takes a long time.Cause: Large number of classes/functions to scan.Solution: Disable tab completion:

return [
    'useTabCompletion' => false,
];

Or disable autoload warming:

return [
    'warmAutoload' => false,
];

Platform-Specific Issues

Windows: Colors not working

Problem: No colored output on Windows.Solution: Use Windows Terminal or enable ANSI support:In PowerShell:

$env:ANSICON = 1
psysh

Or in config:

return [
    'colorMode' => \Psy\Configuration::COLOR_MODE_FORCED,
];

Windows: pcntl not available

Problem: Process forking features unavailable.Cause: pcntl extension doesn’t exist on Windows.Solution: This is a Windows limitation. Use fallback signal handler:

return [
    'usePcntl' => false,
];

Note: Fatal errors will crash PsySH without pcntl.

macOS: Readline behaves differently

Problem: macOS uses libedit instead of GNU Readline.Solution: Install GNU Readline:

brew install php --with-readline

Or configure libedit in ~/.editrc:

bind ^R em-inc-search-prev

Getting More Help

If your issue isn’t covered here:

Check version: Make sure you’re running the latest version:
```
composer global update psy/psysh
```

Enable debug output:

return [
    'verbosity' => \Psy\Configuration::VERBOSITY_DEBUG,
];

Search issues: Check GitHub Issues
Report a bug: Open a new issue with:
- PsySH version (psysh --version)
- PHP version (php -v)
- Operating system
- Steps to reproduce
- Error messages

Get Started

Usage Guide

Commands

Configuration

Advanced

Troubleshooting

Installation Issues

Runtime Errors

Configuration Issues

Autoloading Issues

Display Issues

Readline Issues

Manual/Documentation Issues

Permission Issues

Performance Issues

Platform-Specific Issues

Getting More Help

Build docs developers (and LLMs) love

Get Started

Usage Guide

Commands

Configuration

Advanced

​Installation Issues

​Runtime Errors

​Configuration Issues

​Autoloading Issues

​Display Issues

​Readline Issues

​Manual/Documentation Issues

​Permission Issues

​Performance Issues

​Platform-Specific Issues

​Getting More Help

Build docs developers (and LLMs) love

Installation Issues

Runtime Errors

Configuration Issues

Autoloading Issues

Display Issues

Readline Issues

Manual/Documentation Issues

Permission Issues

Performance Issues

Platform-Specific Issues

Getting More Help