Hooks, MCP, and plugin issues

This page helps troubleshoot issues related to Hooks, MCP servers, and plugins.

First Checks

Before diving into specific components, rule out the two most common causes:

Directory Trust: Untrusted workspaces will not load project-level settings, Hooks, MCP servers, and project-level Agents (Hooks are directly blocked in interactive sessions). When entering a directory for the first time, a trust prompt appears, allowing you to choose "this session only" or "remember" (written to settings.local.json). You can also use permissions.trustDirectories to permanently trust frequently used directories. See Permissions and Directory Trust.
Reload After Configuration Changes: Most extensions support hot reload, which is faster than restarting—/mcp reload, /plugins reload, /skills reload, /agents reload. However, configuration items marked as "requires restart" still require restarting the CLI.

When a Hook is not triggered or behaves abnormally:

Events and Matching: Ensure the event name bound to the Hook is correct, and that matcher can match the target (empty or * matches all, exact values, | for multiple values, or regex).
Exit Codes: command type Hooks use exit codes to control the flow—0 for success, 2 to block (stderr is fed back to the Agent), and others for non-blocking errors. If a Hook unexpectedly blocks an operation, check if it returned 2.
Input Parsing: Hooks receive JSON from stdin (including session_id, cwd, hook_event_name, etc.). Ensure the script reads it correctly.
Executable Permissions: The script pointed to by command must have executable permissions and the correct path.
Use /hooks to view registered Hooks.
For the complete reference, see Hooks reference.

When an MCP server is not connected or tools are unavailable:

Use /mcp to check the server connection status.
Commands and Paths: For stdio type, ensure command, args, and cwd are correct, and the server can start independently.
Project-Level Approval: Project-level MCP servers require individual approval by default. Use mcp.enableAllProjectMcpServers or mcp.enabledProjectMcpServers to approve them.
Allowlist Restrictions: Check if it has been filtered out by mcp.allowed / mcp.excluded, --allowed-mcp-server-names, or --strict-mcp-config.
Authentication: For HTTP/SSE types, ensure the authentication information in headers is correct.
Timeouts: If the connection is slow, adjust the timeout field.
MCP configuration items are marked as "requires restart". After modification, try /mcp reload first; if it still doesn't take effect, restart.
For the complete reference, see MCP reference.

When a plugin is not loaded or components are missing:

Use /plugins to view installed plugins.
Manifest: The manifest is located at .qoder-plugin/plugin.json (can be omitted); if declared, ensure name is valid (kebab-case, no spaces).
Directory Structure: Components must be located in the agreed directories (commands/, agents/, skills/, hooks/hooks.json, .mcp.json, etc.), or their paths must be explicitly declared in the manifest.
Security Restrictions: When security.blockGitExtensions is true, loading plugins from Git is blocked; when security.allowedExtensions is not empty, only matching sources are allowed.
For the complete reference, see Plugin Reference.