Skip to content
MARKO DOCS

Troubleshooting

This page covers the most common issues encountered when setting up marko/devai, marko/mcp, and marko/lsp.

Installation failures

Section titled “Installation failures”

”marko command not found” after composer require

Section titled “”marko command not found” after composer require”

The marko binary is published to vendor/bin/. If you don’t already have it on your PATH from a global install, add the project’s vendor/bin/ to your shell:

Terminal window
export PATH="vendor/bin:$PATH"

Or invoke the binary by its project-local path: ./vendor/bin/marko ....

devai:install exits with “No agents detected”

Section titled “devai:install exits with “No agents detected””

The installer detects agents by looking for known configuration files and binaries. If no agents are found:

  1. Confirm the agent’s CLI is on your PATH (e.g., claude, codex, gemini for the agents that gate detection on a binary).
  2. Bypass detection and force a specific agent set with the --agents flag (comma-separated, no space):
Terminal window
marko devai:install --agents=claude-code,codex

Supported agent identifiers: claude-code, codex, cursor, copilot, gemini-cli, junie.

Permission denied writing agent files

Section titled “Permission denied writing agent files”

If the installer cannot write CLAUDE.md or other files, check directory permissions:

Terminal window
ls -la . | head -5

If running inside a container or mounted volume, ensure the working directory is writable by the PHP process.

MCP server problems

Section titled “MCP server problems”

Agent reports “MCP server failed to start”

Section titled “Agent reports “MCP server failed to start””
  1. Confirm marko mcp:serve runs without error:
Terminal window
marko mcp:serve
# Should block waiting for stdin — press Ctrl+C to exit
  1. Check the agent’s MCP configuration file references the correct command:
{
  "command": "marko",
  "args": ["mcp:serve"]
}
  1. Ensure the marko binary is on the PATH the agent uses. Some agents (e.g., Claude Code) launch their MCP servers in a restricted environment. If marko is not on the agent’s PATH, point the registration at the absolute path of the binary:
{
  "command": "/absolute/path/to/marko",
  "args": ["mcp:serve"]
}

“Tool not found” when calling search_docs

Section titled ““Tool not found” when calling search_docs”

The search_docs tool is only registered when a DocsSearchInterface binding is present. This requires installing a docs driver package such as marko/docs-fts. If no driver is installed, the tool will not appear in the MCP tool list regardless of the index state.

If the tool is listed but returns no results, the index may be stale. Trigger a rebuild:

Terminal window
marko indexer:rebuild

The IndexCache also rebuilds automatically on next read if any tracked source file is newer than the cache.

”Tool not found” when calling query_database

Section titled “”Tool not found” when calling query_database”

The query_database tool is only registered when marko/database is bound in the container. Install the database package and ensure it is configured before expecting this tool to appear.

LSP problems

Section titled “LSP problems”

No completions appearing in the editor

Section titled “No completions appearing in the editor”
  1. Confirm marko lsp:serve runs:
Terminal window
marko lsp:serve
# Should block waiting for stdin — press Ctrl+C

  1. Check the editor’s LSP configuration points to marko lsp:serve.

  2. In VS Code: open the Output panel, select “Marko Language Server” from the dropdown — connection errors appear here.

  3. In PhpStorm: check Settings > Languages & Frameworks > Language Servers for connection status.

Completions appear but are stale or incorrect

Section titled “Completions appear but are stale or incorrect”

The MCP and LSP servers lazy-load .marko/index.cache and rebuild it whenever a watched source file is newer than the cache, so completions usually self-heal. If they don’t, force a clean rebuild:

Terminal window
marko indexer:rebuild

Agent registration problems

Section titled “Agent registration problems”

CLAUDE.md / AGENTS.md not updated after re-running devai:install

Section titled “CLAUDE.md / AGENTS.md not updated after re-running devai:install”

A second marko devai:install run is a no-op once .marko/devai.json exists — the orchestrator prints “Prior install detected at .marko/devai.json. Use marko devai:update to update, or pass —force to re-run.” To force a refresh:

Terminal window
marko devai:install --force

This regenerates the Marko section in every agent guidelines file based on the current set of installed packages.

Guidelines from a newly installed package are not appearing

Section titled “Guidelines from a newly installed package are not appearing”

After adding a new package, re-run the installer:

Terminal window
composer require my-vendor/my-package
marko devai:install

The installer reads resources/ai/guidelines.md from every package in vendor/ each time it runs.

Getting more help

Section titled “Getting more help”