Troubleshooting

This guide covers common problems you might encounter when using Retina and how to resolve them.

Installation issues

Command not found after installation

Problem: Running retina after installation shows “command not found”.

Check installation location

Verify Retina was installed correctly:

ls -la ~/.retina/bin/retina

Add to PATH

The installation script should add Retina to your PATH. If not, add it manually:Bash:

echo 'export PATH="$HOME/.retina/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Zsh:

echo 'export PATH="$HOME/.retina/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Verify

retina --version

PHP version mismatch

Problem: Error message about PHP version requirements.

Retina requires PHP 8.1 or higher

Check PHP version

php --version

Update PHP

Ubuntu/Debian:

sudo apt-get update
sudo apt-get install php8.1-cli

macOS (Homebrew):

brew install [email protected]

Set default PHP

If you have multiple PHP versions:

sudo update-alternatives --set php /usr/bin/php8.1

Composer dependencies missing

Problem: Errors about missing classes or autoloader.

Navigate to Retina directory

cd ~/.retina

Install dependencies

composer install --no-dev --optimize-autoloader

Configuration issues

”Invalid directory path specified”

Problem: Retina can’t find the plugin directory.

Solution

Make sure you’re running Retina from the plugin root directory or specifying the correct path:

# Run from plugin root
cd /path/to/plugin
retina run

# Or specify path
retina run /path/to/plugin

Verify the directory contains a plugin.yml file:

ls -la plugin.yml

“No plugin.yml found”

Problem: Retina reports missing plugin.yml file.

No plugin.yml found in /path. Is this a PocketMine-MP plugin?

Verify plugin structure

PocketMine-MP plugins must have a plugin.yml in the root directory:

my-plugin/
├── plugin.yml    ← Must exist here
├── src/
└── resources/

Check file name

The file must be named exactly plugin.yml (lowercase, with .yml extension).

Verify permissions

ls -la plugin.yml
chmod 644 plugin.yml

Configuration file not being read

Problem: Settings in retina.yml are being ignored.

Command line options always override configuration file settings.

Check file location

retina.yml must be in the plugin root directory:

ls -la retina.yml

Validate YAML syntax

Use a YAML validator to check for syntax errors:

php -r "print_r(yaml_parse_file('retina.yml'));"

Check indentation

YAML is sensitive to indentation. Use spaces, not tabs:

# Correct
paths:
  - src
  - lib

# Wrong (mixed tabs/spaces)
paths:
	- src
  - lib

Invalid category/analyzer names

Problem: Error about invalid categories or analyzers.

Invalid category: unused_varible

Category and analyzer names are case-sensitive and must match exactly.

Common category names:

undefined_variable (not undefined_var)
unused_variable (not unused_var)
deprecated_api (not deprecatedApi)
thread_safety (not threadsafety)

Valid analyzer names:

PluginYml, MainClass, PhpFile
EventHandler, Listener, Command
DeprecatedApi, ThreadSafety, PHPStan

See the configuration guide for complete lists.

Analysis issues

Memory limit errors

Problem: PHP runs out of memory during analysis.

Fatal error: Allowed memory size of 134217728 bytes exhausted

Increase PHP memory limit

Run Retina with a higher memory limit:

php -d memory_limit=512M ~/.retina/bin/retina run

Update php.ini

For a permanent fix, edit php.ini:

memory_limit = 512M

Find your php.ini:

php --ini | grep "Loaded Configuration File"

Exclude large directories

Add large directories to excludePaths:

excludePaths:
  - vendor
  - node_modules
  - build
  - cache

Scan takes too long

Problem: Analysis is very slow on large plugins.

Exclude paths
Disable analyzers
Lower strictness
Limit scan paths

Exclude directories that don’t need scanning:

excludePaths:
  - vendor
  - tests
  - docs
  - examples

Disable slow analyzers you don’t need:

excludeAnalyzers:
  - PHPStan  # PHPStan can be slow on large codebases

Reduce the analysis level:

level: 4  # Faster but less thorough

Only scan specific directories:

paths:
  - src  # Only scan source code

False positives

Problem: Retina reports issues that aren’t actually problems.

Lower strictness level

Higher levels produce more false positives:

level: 5  # More lenient

Ignore specific errors

Use ignoreErrors to suppress false positives:

ignoreErrors:
  - "#Variable \$logger is never read#"
  - "#Property.*is never read#"

Exclude categories

Exclude entire categories if they’re problematic:

excludeCategories:
  - unused_parameter  # Common false positive

Use baseline

For existing codebases with many false positives:

baseline: retina-baseline.neon

Missing expected issues

Problem: Retina doesn’t catch issues you know exist.

Increase strictness level

level: 8  # More thorough analysis

Enable all rules

Make sure the relevant rules are enabled:

rules:
  deprecatedApiUsage: true
  threadSafetyViolation: true
  # ... enable other rules

Check exclude filters

Remove or adjust filters that might be hiding issues:

excludeCategories: []  # Remove all exclusions
excludeSeverities: []  # Show all severity levels

Verify scan paths

Ensure the file is in a scanned directory:

paths:
  - src
  - lib  # Make sure this includes the file

Report generation issues

Empty or missing reports

Problem: Report file isn’t created or is empty.

Console-only mode enabled

If you used -c or --console-only, no file is created:

# This creates a file
retina run -f md -o report.md

# This doesn't
retina run -c

Permission denied

Check write permissions in the output directory:

ls -la .
chmod 755 .

No issues found

Some formats only create files when issues are found. Use --console-only to verify:

retina run -c

Corrupted JSON output

Problem: JSON report can’t be parsed.

Validate JSON

jq . retina-report.json

Check for mixed output

If running with --console-only and redirecting, you might have mixed console output:

# Wrong - mixes console output with JSON
retina run -f json -c > output.json

# Right - saves only JSON
retina run -f json -o output.json

Use simple format

Simple format is smaller and less prone to issues:

retina run -f json -s -o output.json

HTML report not displaying properly

Problem: HTML report shows unstyled content or doesn’t render.

Check file encoding

Ensure the file is UTF-8 encoded:

file retina-report.html

Try different browser

Some browsers have strict local file policies. Try:

Opening in a different browser
Serving via a local web server:

php -S localhost:8000
# Then visit http://localhost:8000/retina-report.html

Check for truncation

Ensure the file was completely written:

tail -n 20 retina-report.html
# Should end with </html>

CI/CD issues

Exit code always 0 or always 1

Problem: Retina’s exit code doesn’t match expected results.

Retina returns exit code 1 if ANY issues are found, regardless of severity.

Filter issues for CI

Exclude low-severity issues to control when builds fail:

retina run --exclude-severities=hint,info

Use continue-on-error

Allow the pipeline to continue:

- name: Run Retina
  continue-on-error: true
  run: retina run

Parse JSON for custom logic

Extract specific metrics and decide when to fail:

ERRORS=$(jq '.summary.bySeverity.error // 0' retina-report.json)
if [ "$ERRORS" -gt 0 ]; then
  exit 1
fi

Installation fails in CI

Problem: Can’t install Retina in CI environment.

Missing dependencies

Install required packages first:

- name: Install dependencies
  run: apt-get update && apt-get install -y git curl php8.1-cli

Permission issues

Use a writable directory:

curl -sSL https://raw.githubusercontent.com/chinmay505/retina/main/install.sh | bash
export PATH="$HOME/.retina/bin:$PATH"

Network restrictions

If the CI environment blocks external downloads:

Pre-install Retina in a Docker image
Cache the installation
Include Retina in your repository

Reports not uploaded as artifacts

Problem: CI doesn’t save or display reports.

Use when: always

Ensure artifacts are uploaded even on failure:

- name: Upload report
  if: always()
  uses: actions/upload-artifact@v4
  with:
    name: retina-report
    path: retina-report.json

Verify report was created

Add a verification step:

- name: Verify report exists
  run: |
    if [ ! -f retina-report.json ]; then
      echo "Report not created!"
      exit 1
    fi

Check artifact paths

Ensure the path matches where Retina creates the file:

# Default location
path: retina-report.md

# Custom location
path: custom/path/report.json

Performance issues

High memory usage

Problem: Retina uses too much RAM.

Use simple reports

Simple reports use less memory:

simpleReport: true

Exclude large files

excludePaths:
  - vendor
  - node_modules
  - "*.min.php"

Lower strictness

Lower levels require less memory:

level: 4

Slow on Windows

Problem: Retina is significantly slower on Windows.

Windows file I/O is generally slower than Unix systems. This is expected.

Exclude Windows Defender

Add the plugin directory to Windows Defender exclusions.

Use WSL2

For better performance, run Retina in WSL2:

wsl
cd /mnt/c/path/to/plugin
retina run

Disable real-time scanning

Temporarily disable antivirus during analysis.

Getting help

If you’re still experiencing issues:

Enable verbose output

Run with verbose flag for more details:

retina run -v

Check the logs

Look for error messages in the console output.

Create a minimal reproduction

Try running Retina on a simple test plugin to isolate the issue.

Report the issue

If you’ve found a bug, report it on GitHub:https://github.com/chinmay505/retina/issuesInclude:

Retina version (retina --version)
PHP version (php --version)
Operating system
Command you ran
Full error message
Configuration file (if applicable)

Get Started

Core Concepts

Guides

Troubleshooting

Installation issues

Command not found after installation

PHP version mismatch

Composer dependencies missing

Configuration issues

”Invalid directory path specified”

“No plugin.yml found”

Configuration file not being read

Invalid category/analyzer names

Analysis issues

Memory limit errors

Scan takes too long

False positives

Missing expected issues

Report generation issues

Empty or missing reports

Corrupted JSON output

HTML report not displaying properly

CI/CD issues

Exit code always 0 or always 1

Installation fails in CI

Reports not uploaded as artifacts

Performance issues

High memory usage

Slow on Windows

Getting help

See also

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

​Installation issues

​Command not found after installation

​PHP version mismatch

​Composer dependencies missing

​Configuration issues

​”Invalid directory path specified”

​“No plugin.yml found”

​Configuration file not being read

​Invalid category/analyzer names

​Analysis issues

​Memory limit errors

​Scan takes too long

​False positives

​Missing expected issues

​Report generation issues

​Empty or missing reports

​Corrupted JSON output

​HTML report not displaying properly

​CI/CD issues

​Exit code always 0 or always 1

​Installation fails in CI

​Reports not uploaded as artifacts

​Performance issues

​High memory usage

​Slow on Windows

​Getting help

​See also

Build docs developers (and LLMs) love

Installation issues

Command not found after installation

PHP version mismatch

Composer dependencies missing

Configuration issues

”Invalid directory path specified”

“No plugin.yml found”

Configuration file not being read

Invalid category/analyzer names

Analysis issues

Memory limit errors

Scan takes too long

False positives

Missing expected issues

Report generation issues

Empty or missing reports

Corrupted JSON output

HTML report not displaying properly

CI/CD issues

Exit code always 0 or always 1

Installation fails in CI

Reports not uploaded as artifacts

Performance issues

High memory usage

Slow on Windows

Getting help

See also