Skip to main content

Troubleshoot Skills, MCP, Plugins, and Hooks

Start with the symptom below. Keep the exact error text, but remove account details, credentials and private task content before sharing it. Reinstalling is not the first step: an installed plugin can still need a service connection, an enabled Skill or permission for the requested action.

Skills​

Not found or not triggered​

  1. Open Plugins → Skills. Clear the search, select All skills, and turn Archived off.
  2. Find the Skill and open its details. For duplicate names, expand its source label and check the file path.
  3. Check Enable in Ghast. For a plugin Skill, also check that its plugin is installed and enabled.
  4. If you just added or edited a local Skill, choose Refresh skills. Its directory must contain SKILL.md with a valid name and description.
  5. For a deliberate test, choose Try now and add a small task matching the instructions. This creates a new draft; review it before sending.
  6. Inspect the response and tool results. Being enabled makes a Skill available; it does not mean every message will use it.

For archived Skills, switch to Archived, find the item and choose Restore before checking its enabled state. See Manage the Skills library for the complete procedure.

Dependency failure​

Read the failed tool result for the missing program or command. Check the Skill's instructions and platform requirements before installing anything. Use the publisher's documented setup; do not run an unfamiliar installer supplied by an error message. If asking for help, include the program name, operating system and redacted error—not your entire task history.

MCP​

Cannot connect​

  1. Open Plugins → Manage connections and locate the affected service.
  2. Read its connection diagnostics. A missing command or exited process points to local setup; an unauthorized response points to credentials; a timeout can indicate a network or endpoint problem.
  3. For a plugin connection, use its Connect or Reconnect flow and confirm the intended account.
  4. For a custom server, open its settings and compare the transport, command or URL, arguments and required credentials with the publisher's setup instructions.
  5. Reconnect after correcting the specific problem, then test one read-only request.

Do not expose environment values or request headers in screenshots: custom server editing can display saved credentials. See Add an MCP server for local and remote setup.

Connected but no Tools​

  1. Confirm that the selected model supports tools.
  2. State the intended service and read-only operation explicitly. Do not look for a server group in Add: the current composer has no tool picker.
  3. Check that the plugin is enabled and the server is connected.
  4. Look for a tool-change alert in Manage connections and review it as described below.
  5. Reconnect, inspect any partial result, and retry a small read-only request. If only resources are available, the server may not publish tools.

A connected session does not prove that a particular tool call succeeded. See Use MCP tools for a first-call checklist.

A tool is paused after a server update​

Open Plugins → Manage connections, find the tool-change alert and choose Review. Compare the previous and new descriptions and inputs. Check whether the update changes the account or data range, adds write actions, or changes important defaults.

Approve only when you understand the change. If you cannot explain it, leave the tool paused and ask the publisher. Approval accepts that version of the tool definition; it does not authorize every future action. See Review MCP access and changes.

Plugins​

Installation fails​

  1. Read the installation error and check whether the catalog marks the package incompatible.
  2. Choose Refresh in the plugin library, then reopen its detail page.
  3. If the catalog or package cannot be downloaded, check your network/proxy and the source URL.
  4. For Install local, select the plugin root, not a parent directory or an individual Skill directory.
  5. If the error names an invalid manifest or missing package file, ask the author for a corrected package. Plugin authors can use the package reference.

Retry after correcting the cause. Do not delete conversations, replace credentials or remove unrelated plugins to repair a package error.

Installed but unavailable in a conversation​

Open the plugin's detail page and check its enabled state, individual Skill switches and app connections separately. Installing does not sign you into its external services. A Skill switch does not enable every other capability in the package.

Try a supplied starter prompt, review the resulting draft and send a small read-only task. If the tool is still missing, follow the MCP checks above. If the tool runs but fails, use its returned error and verify any partial result before retrying. See Browse, install, and use plugins.

Plugin Hooks​

Start with Use plugin Hooks. Confirm the plugin is Enabled, its required runtime is installed, and its own mode allows the intended behavior. A Skill switch or a missing @mention does not stop an enabled plugin's Hooks.

If an error says the plugin blocked a request, read its reason and resolve the prerequisite. If sending is slow or guidance is missing, ask the author to check command failures and timeouts. A timeout continues without that command's context; it does not block the request as a policy decision.

Authors should check the event, matcher, command path, standard input, and output using Write a plugin Hook. Test a harmless command first. Do not paste private messages or credentials into a bug report.

Context​

In the current conversation, select only the skills and tools the task needs. Avoid disconnecting a shared account merely to shorten one conversation. Open Context usage beside the composer; for a long history, follow Manage context compaction. A plugin mention helps select capabilities but is not an exclusive permission boundary.