Troubleshooting Common Issues

This page documents known error conditions and their resolutions. Issues are grouped by environment. For multi-project switching issues (stale mcp.json), see page 2.4. For platform-specific MCP path details, see page 2.3 and page 5.3.

Known Error Conditions

Symptom	Cause	Section
wslvar: command not found	wslu package not installed in WSL	WSL
WSL Interoperability is disabled error	binfmt configuration missing	WSL Interoperability Disabled
PowerShell commands fail from WSL	Windows interop not functioning	PowerShell Inaccessible from WSL
Exception: Testbench is not supported	Running boost:install inside a package test harness	Testbench Not Supported
PhpStorm Remote Dev (PhpStorm running inside WSL) cannot auto-configure	Environment indistinguishable from native Linux	PhpStorm Remote Dev in WSL
MCP config file not written	Permission or path issue	Configuration File Not Created
Sail MCP commands fail	Sail container not running	Laravel Sail Problems

Sources: README.md29-88 src/PhpStormCopilot.php119-132 src/Concerns/WithWSL.php11-76

Diagnostic Flow

Diagram: installFileMcp guard logic and branching

Sources: src/PhpStormCopilot.php119-132 src/PhpStormCopilot.php183-185 src/Concerns/WithWSL.php11-13

WSL: wslu/wslvar Not Installed

Symptom

wslvar: command not found

Or installMcpViaWsl fails silently — the MCP config is not written to the Windows filesystem.

Root Cause

installMcpViaWsl in src/Concerns/WithWSL.php16-76 calls wslvar LOCALAPPDATA as its first step to resolve the Windows AppData\Local path. This command is provided by the wslu utility package. If wslu is not installed, the process result is empty and the method returns false early at src/Concerns/WithWSL.php22-24

Diagram: installMcpViaWsl dependencies

Diagnosis

Expected: wslvar LOCALAPPDATA returns C:\Users\YourUsername\AppData\Local.

Solution

Verify with wslvar -v, then re-run:

Note: Your Windows user profile must be on the C: drive. Non-default user profile locations are not supported.

Sources: README.md29-44 src/Concerns/WithWSL.php16-76

WSL Interoperability Disabled

Symptom

[error] WSL Interoperability is disabled. Please enable it before using WSL.

Root Cause

installMcpViaWsl src/Concerns/WithWSL.php16-76 invokes powershell.exe and other Windows executables directly from WSL. This requires the WSL binfmt interoperability layer to be active. If the binfmt configuration for Windows PE binaries is missing, these calls fail.

Solution

Add the WSL Interop binfmt entry and restart the service:

Verify with:

Then re-run:

Sources: README.md55-59 src/Concerns/WithWSL.php16-76

---

PowerShell Inaccessible from WSL

Symptom

powershell.exe commands fail or are not found, even though wslvar works. The MCP config file is not written.

Root Cause

installMcpViaWsl at src/Concerns/WithWSL.php30-31 runs a powershell.exe command to read the existing mcp.json. Later, at src/Concerns/WithWSL.php58-60 and src/Concerns/WithWSL.php68-72 it writes the updated config using powershell.exe with Base64-encoded content. If powershell.exe is inaccessible, all three calls fail.

Diagnosis

Both commands must succeed.

Solution

If powershell.exe is not found, WSL interoperability is the underlying issue. Follow the steps in WSL Interoperability Disabled

If powershell.exe is found but returns errors, verify directory permissions on the Windows side:

Sources: README.md50-54 src/Concerns/WithWSL.php28-75

Testbench Not Supported

Symptom

Exception: Testbench is not supported. Consider using laravel-boost-copilot-cli instead.

This exception is thrown when running boost:install --mcp inside a Laravel package that uses orchestra/testbench as its test harness.

Root Cause

installFileMcp in src/PhpStormCopilot.php119-132 calls isRunningInTestbench() src/PhpStormCopilot.php183-185 as its first guard. isRunningInTestbench checks for the TESTBENCH_CORE constant defined by orchestra/testbench. If the constant is present, an Exception is thrown unconditionally.

The reason for this restriction is that inside a Testbench environment the Laravel application root does not correspond to a real project directory, so the absolute paths that would be written to mcp.json would be meaningless.

Solution

Use laravel-boost-copilot-cli instead. That tool uses a project-local MCP configuration file rather than the system-wide mcp.json, making it compatible with package development workflows.

Sources: README.md86-88 src/PhpStormCopilot.php119-125 src/PhpStormCopilot.php183-185

---

PhpStorm Remote Dev in WSL

Symptom

Running boost:install --mcp when PhpStorm itself is launched via Remote Development inside WSL (i.e., the IDE process runs within the WSL Linux environment) does not write the configuration to the correct location.

Root Cause

The isWSL() method in src/Concerns/WithWSL.php11-13 detects WSL by checking the WSL_DISTRO_NAME environment variable. However, when PhpStorm Remote Dev runs inside WSL, that environment variable is not set from PhpStorm's perspective — the setup is indistinguishable from a plain Linux installation. Therefore the package treats it as native Linux and writes mcp.json to ~/.config/github-copilot/intellij/mcp.json inside WSL, not to the Windows filesystem where PhpStorm on the Windows host would look.

There is no automatic way to distinguish "native Linux" from "PhpStorm Remote Dev on WSL". This is a known limitation.

Solution: Manual Configuration

Manually write mcp.json to the Linux path that PhpStorm Remote Dev reads:

File path: ~/.config/github-copilot/intellij/mcp.json

Replace both paths with values from which php and the absolute path to your project's artisan file.

Sources: README.md62-81 src/Concerns/WithWSL.php11-13 src/PhpStormCopilot.php104-114

---

Configuration File Not Created

Symptom

After running php artisan boost:install --mcp, the MCP configuration file does not exist at the expected location and no error is shown.

Expected Locations

The mcpConfigPath() method src/PhpStormCopilot.php104-114 returns:

Platform	Path
macOS / Linux	~/.config/github-copilot/intellij/mcp.json
Windows	%LOCALAPPDATA%\github-copilot\intellij\mcp.json
WSL	Windows path, written via powershell.exe

Common Causes

Cause	Diagnosis	Solution
wslu not installed (WSL)	wslvar -v fails	Install wslu — see WSL
WSL interop disabled	powershell.exe echo test fails	See WSL Interoperability Disabled
Directory does not exist	ls ~/.config/github-copilot/intellij/ fails	mkdir -p ~/.config/github-copilot/intellij
Permission denied	Cannot write to target path	chmod 755 ~/.config/github-copilot/intellij
Running in Testbench	Exception thrown	See Testbench Not Supported

Solution Steps

1. Confirm which path the package will write to by checking your OS.
2. Create the directory if missing:

3. Fix permissions if needed:

4. Re-run:

Sources: src/PhpStormCopilot.php104-114 src/Concerns/WithWSL.php16-76

Laravel Sail Problems

Symptom

MCP commands fail to execute, or Sail container errors appear when PhpStorm invokes the MCP server.

Root Cause

Diagram: Sail command transformation paths

transformSailCommand src/PhpStormCopilot.php141-162 wraps Sail in a bash -c command so that it runs in the correct working directory. transformMcpCommandForWsl src/Concerns/WithWSL.php85-129 uses wsl.exe --cd instead. Both approaches require Sail to already be running when PhpStorm invokes the MCP server.

Solution

1. Start Sail before using Copilot:

2. Re-run installation if configuration was generated while Sail was stopped:

3. Verify the generated command manually:

Sources: README.md21-23 src/PhpStormCopilot.php141-162 src/Concerns/WithWSL.php85-129

Permission and Path Issues

Platform-Specific MCP Paths

The mcpConfigPath() method src/PhpStormCopilot.php104-114 returns:

Platform	Path
macOS (Darwin)	~/.config/github-copilot/intellij/mcp.json
Linux	~/.config/github-copilot/intellij/mcp.json
Windows	%LOCALAPPDATA%\github-copilot\intellij\mcp.json

Common Permission Issues

Issue	Symptom	Solution
Directory not writable	File not created	chmod 755 ~/.config/github-copilot/intellij
File not writable	Cannot update existing config	chmod 644 ~/.config/github-copilot/intellij/mcp.json
Parent directory missing	Path not found	mkdir -p ~/.config/github-copilot/intellij
WSL Windows path access	File not created in Windows	Check wslvar LOCALAPPDATA works

Sources: src/PhpStormCopilot.php104-114

Debugging MCP Configuration Content

Viewing Current Configuration

Expected Structures by Environment

Native macOS/Linux:

WSL (standard):

WSL with Sail:

Native macOS/Linux with Sail:

Note: removeEmptyArrays src/PhpStormCopilot.php168-181 is applied before writing — empty arrays are stripped to avoid incompatibility with some MCP clients.

Sources: src/PhpStormCopilot.php119-132 src/PhpStormCopilot.php168-181 src/Concerns/WithWSL.php40-75

Verifying System Detection

Checking Platform Detection

systemDetectionConfig src/PhpStormCopilot.php39-67 declares which file paths are checked per platform to determine if PhpStorm is installed:

Verifying That boost:mcp Works

Before relying on Copilot, confirm the MCP server starts correctly:

If these succeed but mcp.json is still wrong, the issue is in the file write path (installFileMcp src/PhpStormCopilot.php119-132 or installMcpViaWsl src/Concerns/WithWSL.php16-76), not in path detection.

Sources: src/PhpStormCopilot.php39-67 src/PhpStormCopilot.php119-132

Getting Further Help

If none of these solutions resolve your issue:

1. Check GitHub Issues: Search for similar problems at https://github.com/invokable/laravel-boost-phpstorm-copilot/issues

2. Gather diagnostic information:

3. Alternative tool: Consider using laravel-boost-copilot-cli which uses project-local MCP configuration files instead of system-wide configuration, avoiding many of these issues.

Sources: README.md84 README.md88