Troubleshooting

Fix an MCP connection

The coding client starts a local Artisan process. Test that command and its environment before changing your debugging prompt.

  1. Client

    Starts the configured executable with the Artisan path and arguments.

  2. Laravel process

    Boots the intended app and registers The New Debug Bar server.

  3. Saved profiles

    The five tools read profiles from that app’s configured storage.
A client can connect successfully and still read the wrong app or an empty profile directory.

Check the executable and the application

Start with the command recorded in your client setup. The executable must exist, and the Artisan path must belong to the app you are debugging. Check the same PHP runtime:

/absolute/path/to/php -v /absolute/path/to/php /absolute/path/to/your-app/artisan env

Replace both paths. A desktop client may not inherit your shell’s PHP path, aliases, or environment. For Docker or Sail, use a command that starts PHP inside the application container; see Local environments.

Read a startup failure before retrying

Check the client’s MCP log for the first startup error. Missing PHP, a missing Artisan file, a Composer/autoload failure, or a Laravel bootstrap exception must be resolved before tool discovery can work.

Confirm that the process uses an allowed environment and that NEWDEBUGBAR_ENABLED is not false. If configuration changed, clear the app’s configuration cache and restart this MCP connection.

If the client reports malformed JSON or invalid protocol output, check for application startup code writing banners, echo, dump(), or dd() to standard output. Keep protocol output separate from application logs.

Confirm the five tools are available

  • list-debug-profiles
  • get-debug-profile-inspector
  • get-debug-profile-data
  • inspect-debug-queries
  • get-debug-findings

Restart the connection after fixing startup. If the server is listed but these tools are absent, inspect the initialization error and confirm the client started this app’s newdebugbar server.

Connected, but no profiles appear?

Visit one page in the Laravel app and read its X-NewDebugBar-Profile header. Ask the agent to open that exact ID. An empty list is a data or environment check, not proof of a connection failure.

Check that the browser PHP process and MCP process use the same profile directory and can read its files. Host PHP, containers, worktrees, and remote machines can have different directories with similar-looking paths.

Use missing-profile checks for retention, omitted data, and a profile that has expired.

Distinguish missing data from a tool error

Result Next step
status: ok Read the response and continue with its returned paths or cursor.
status: not_found Check the exact ID, requested inspector or path, and retention. The missing object may be a path rather than the whole profile.
Tool error with status: partial Use the retained data, inspect background_error, and retry background refresh. Treat background_pending: null as unknown.
Other processing or storage error Read the reported error. Do not relabel it as an expired profile.

Prove the connection works

Capture one fresh request, list it, and read its Request or Queries inspector. Compare method, path, and a visible metric with the browser. You now have proof that the client can read the intended app’s actual saved data.

Next step

Debug one problem from start to finish

Use the working connection to trace a repeated query and verify a focused change.

Read the guide