VOOZH about

URL: https://deepwiki.com/invokable/laravel-boost-copilot-cli/7.4-troubleshooting

⇱ Troubleshooting | invokable/laravel-boost-copilot-cli | DeepWiki

Loading...
Loading...
Last indexed: 7 March 2026 (397730)
Menu

Troubleshooting

This page documents common issues encountered when using Laravel Boost with GitHub Copilot CLI, their diagnostic steps, and solutions. It covers MCP server configuration problems, environment-specific issues, and guideline loading failures.

For configuration file structure details, see Configuration Files Reference. For command syntax, see Command Reference. For environment-specific setup instructions, see Environment-Specific Setup.

Quick Diagnostic Checklist

Use this checklist to identify the category of your issue:

SymptomLikely CauseSection
Copilot CLI does not show "Configured MCP servers: laravel-boost"MCP configuration not loadedMCP Server Not Detected
MCP server detected but tools unavailableInvalid configuration or command pathMCP Tools Not Available
Tools work but return empty/limited resultsEnvironment-specific limitationsEnvironment-Specific Issues
Guidelines not appearing in Copilot responsesKnown Copilot CLI limitationGuidelines Not Loading
boost:install fails or generates wrong configEnvironment detection issueInstallation Issues

Sources: README.md1-133 .github/instructions/laravel-boost.instructions.md1-254

MCP Server Not Detected

Symptoms

When starting Copilot CLI, you do not see the message:

Configured MCP servers: laravel-boost

Diagnosis Flow



Solution 1: Missing Configuration Flag


The most common issue is forgetting to specify the MCP configuration file when starting Copilot CLI.


Required Command:




You can continue an existing session with:




Shell Function for Automatic Loading:


To avoid manually specifying the flag, add this function to .bashrc or .zshrc README.md78-93:




Sources: README.md55-99 .github/instructions/laravel-boost.instructions.md6-13 .ai/guidelines/copilot-cli.blade.php3-9


Solution 2: Missing Configuration File


If .github/mcp-config.json does not exist, run the installation command:


Standard Laravel Application:




Testbench Environment:




Select the following during installation:


    

  • Features: ☑ Boost MCP Server Configuration
    • 

  • Agents: ☑ GitHub Copilot CLI
    • 



Sources: README.md35-53 docs/testbench.md54-78


Solution 3: Invalid JSON Syntax


Validate your .github/mcp-config.json structure. The required format is .github/copilot-instructions.md37-90:




Common syntax errors:


    

  • Missing trailing commas
    • 

  • Incorrect quote types
    • 

  • Malformed array syntax
    • 



Sources: .github/mcp-config.json1-14 .github/copilot-instructions.md37-90




MCP Tools Not Available


Symptoms


MCP server is detected, but tools do not appear or fail when invoked.


Environment-Specific Command Paths




Solution 1: Incorrect Command Path


Verify the command and args in .github/mcp-config.json match your environment:



























EnvironmentCommandArgs
Standard Laravelphp["artisan", "boost:mcp"]
Laravel Sail./vendor/bin/sail["artisan", "boost:mcp"]
Testbench./vendor/bin/testbench["boost:mcp"]


Sources: .github/copilot-instructions.md40-90


Solution 2: Relative Path Issues


If using relative paths (e.g., ./vendor/bin/sail), ensure you start Copilot CLI from the project root directory.


Verification:




If the command fails, the MCP server will also fail to start.


Sources: .github/mcp-config.json5-8


Solution 3: File Permissions


Ensure executable scripts have proper permissions:




Sources: Files referenced in .github/copilot-instructions.md55-72




Environment-Specific Issues


Testbench Environment


Limited Tool Availability




When using Testbench for package development, several MCP tools may not work as expected because there is no full application context .github/instructions/laravel-boost.instructions.md15-24:


Tools with Limitations:


    

  • database-query - No application database configured
    • 

  • database-schema - No application schema
    • 

  • list-routes - No application routes defined
    • 

  • Model-specific operations - No application models
    • 



Tools That Work:


    

  • application-info - Basic environment info
    • 

  • list-artisan-commands - Package and base commands
    • 

  • search-docs - Documentation search
    • 

  • tinker - Limited to package classes
    • 



Sources: .github/instructions/laravel-boost.instructions.md15-24 .ai/guidelines/copilot-cli.blade.php11-21 docs/testbench.md1-87


Cache/Database Setup Issues


Problem: MCP server fails to start due to missing cache database.


Solution 1: Use Workbench Build (Recommended)


docs/testbench.md10-38:




Solution 2: Use Array Cache


docs/testbench.md42-51:


Add to testbench.yaml:




Sources: docs/testbench.md1-87


APP_ENV Configuration


Ensure APP_ENV is set to local in testbench.yaml docs/testbench.md40-41:




Sources: docs/testbench.md40-51


Laravel Sail


Sail Not Running


Problem: MCP server cannot connect to Sail container.


Symptom: Tools timeout or fail with connection errors.


Solution:


Ensure Sail is running before starting Copilot CLI:




Note: The copilot command runs outside of Sail, but it executes commands inside the Sail container README.md27-29


Sources: README.md27-29 .github/copilot-instructions.md55-72


Wrong Command Configuration


Verify .github/mcp-config.json uses Sail-specific configuration:




Sources: .github/copilot-instructions.md55-72


WSL Environment


Path Conversion Issues


Problem: WSL-specific PHP binary paths not properly converted.


The package includes automatic WSL path detection and conversion in the CopilotCli class, but issues may occur if:


    

  • PHP is installed in an unusual location
    • 

  • Multiple PHP versions are present
    • 

  • Windows and WSL paths are mixed
    • 



Verification:


Check that the generated .github/mcp-config.json uses a valid path format for your WSL distribution.


Manual Override:


If automatic detection fails, manually edit .github/mcp-config.json to use the correct PHP path:




Sources: README.md23-24




Guidelines Not Loading


Known Limitation




Issue: Copilot CLI does not load instructions after the < character README.md126-128


This means the <laravel-boost-guidelines> tag in .github/copilot-instructions.md is not processed, and its content from .github/instructions/laravel-boost.instructions.md is not loaded.


Workaround


Manually instruct .github/copilot-instructions.md to include the laravel-boost guidelines content, or directly reference the .github/instructions/laravel-boost.instructions.md file in your instructions.


Current Behavior:
The tag <laravel-boost-guidelines> at .github/instructions/laravel-boost.instructions.md1 and .github/copilot-instructions.md1 is not processed by Copilot CLI.


Impact:


    

  • Laravel Boost-specific guidelines may not be automatically applied
    • 

  • You may need to manually reference tools and conventions
    • 

  • Environment-specific instructions (like Testbench limitations) may not be communicated to Copilot
    • 



Sources: README.md126-128




Installation Issues


boost:install Generates Wrong Configuration




Solution: Environment Detection Override


If automatic environment detection fails:


    

  1. 

    Delete existing configuration:
    

    

    2. 

  2. 

    Manually create correct configuration for your environment using the templates in .github/copilot-instructions.md40-90
    

    3. 

  3. 

    Or force a specific environment:
    

      

    • Ensure vendor/bin/sail exists for Sail detection
      • 

    • Ensure TESTBENCH_CORE is defined for Testbench
      • 

    • Check PHP_BINARY path for WSL detection
      • 

    

    4. 



Sources: .github/copilot-instructions.md37-90


Missing Feature Files


Problem: AI Guidelines or Skills not installed.


Cause: Features not selected during boost:install README.md43-49


Solution:


Re-run installation and select all features:




Select:


    

  • ☑ AI Guidelines → Creates .github/instructions/laravel-boost.instructions.md
    • 

  • ☑ Agent Skills → Creates .github/skills/
    • 

  • ☑ Boost MCP Server Configuration → Creates .github/mcp-config.json
    • 



Sources: README.md43-53




Configuration File Issues


mcp-config.json vs mcp-config.local.json




Local Configuration for Sensitive Data


For MCP servers requiring credentials, use .github/mcp-config.local.json README.md101-124:


Setup:




Example Local Config:




Loading Both Files:


The shell function at README.md78-93 automatically loads both files if they exist.


Sources: README.md101-124




Verification Steps


Verify MCP Server Connectivity




Step-by-Step Verification


    

  1. 

    Test the command directly:
    

    

    The command should start and wait for MCP protocol messages. Press Ctrl+C to exit.
    

    2. 

  2. 

    Verify configuration file exists:
    

    

    3. 

  3. 

    Validate JSON syntax:
    

    

    4. 

  4. 

    Start Copilot with verbose output:
    

    

    Look for: Configured MCP servers: laravel-boost
    

    5. 

  5. 

    Test a basic MCP tool:
    

    In Copilot CLI, ask: "What Laravel version is this project using?"
    

    Copilot should use the application-info tool from the laravel-boost MCP server.
    

    6. 



Sources: README.md55-67 .github/instructions/laravel-boost.instructions.md6-13


Common Success Indicators























IndicatorMeaning
Configured MCP servers: laravel-boostMCP server loaded successfully
Tool calls visible in Copilot outputMCP tools are being invoked
Relevant responses about your applicationTools returning correct data


Common Failure Indicators



























IndicatorLikely Issue
No "Configured MCP servers" messageConfiguration not loaded or invalid
"laravel-boost" server not listedServer failed to start or wrong config
Tool calls fail or timeoutCommand path incorrect or permissions issue
Generic responses without tool usageTools not accessible or disabled


Sources: README.md61 .github/instructions/laravel-boost.instructions.md6-13
Refresh this wiki
On this page