> For the complete documentation index, see [llms.txt](https://mariadb.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://mariadb.com/docs/tools/community/mariadb-ai-plugins/troubleshooting.md).

# Troubleshooting

Common MariaDB AI Plugins error messages and symptoms, what causes them, and how to fix them.

## Error Messages

| Message or symptom                               | Cause                                                                                                          | Fix                                                                                          |
| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| *not a configured connection*                    | The URI isn't on the allow-list, or asks for more than was configured, such as a default schema or an option.  | Add the connection with `mariadb-shell -- mcp setup`, or remove the extra part from the URI. |
| A tool call that never returns                   | A path isn't on the allowed-paths list, and the MCP server is waiting for a confirmation the agent can't give. | Add the directory with `mcp setup`.                                                          |
| *There is no object registered under name 'mcp'* | MariaDB Shell can't find its plugins, usually because its configuration directory was moved or is unreadable.  | Check `~/.mariadb-shell/plugins/`.                                                           |
| No `migrator.*` tools                            | The migration tooling isn't installed, or the MCP server hasn't restarted since it was.                        | Run `mariadb-shell -- mcp setup --installMigrator`, then restart the MCP server.             |
| *No module named 'pywintypes'* on Windows        | The Windows MariaDB Shell packages don't bundle pywin32.                                                       | Install `pywin32` into MariaDB Shell's bundled Python.                                       |

## The Plugin Doesn't Load

Check that the harness loaded the plugin:

* Claude Code: run the following command:

  ```
  /plugin
  ```
* Codex: run the following command:

  ```
  /plugins
  ```
* Pi: a project-local package must be approved at run time with `--approve`, or it is configured but never loaded.
* Hermes Agent: Hermes installs portable packages disabled. Check that the plugin is enabled:

  ```bash
  hermes plugins list
  ```

  To enable it, run `hermes plugins enable mariadb-dev`.
* Cursor: check that the plugin is listed under **Customize**.

## The MCP Server Doesn't Start

* The first start downloads MariaDB Shell, which can take a minute. Check the harness's MCP log; the launcher writes all of its messages to standard error.
* Claude Code waits 30 seconds for an MCP server to connect. When the first download takes longer, `/mcp` lists the `mariadb` server as failed, but the installation continues. Reconnect the server from `/mcp` when the installation is complete, or start a new session. To allow more time, set `MCP_TIMEOUT`. See [Claude Code](https://mariadb.com/docs/tools/community/mariadb-ai-plugins/installation/claude-code.md#first-start).
* To use a MariaDB Shell you installed yourself, set `MARIADB_SHELL_BIN`. See [Configuration Reference](https://mariadb.com/docs/tools/community/mariadb-ai-plugins/configuration-reference.md).
* For Codex, register the server manually. See [Codex](https://mariadb.com/docs/tools/community/mariadb-ai-plugins/installation/codex.md#register-the-mcp-server-manually).
* For Pi, the server requires Pi 1.0 or later and the built-in MCP support of Pi. An installed `pi-mcp-adapter` replaces the built-in support, so the `mariadb` server never connects. Remove the adapter and turn the built-in `mcp` back on. See [Pi](https://mariadb.com/docs/tools/community/mariadb-ai-plugins/installation/pi.md#upgrade-from-pi-mcp-adapter).
* For Hermes Agent, start a new session after the installation, because Hermes connects MCP servers when a session starts. On native Windows, the plugin's `.sh` launcher can't run, so add a `mariadb` server with the `.cmd` launcher to `config.yaml`. See [Hermes Agent](https://mariadb.com/docs/tools/community/mariadb-ai-plugins/installation/hermes.md#windows).

## A Sandbox Doesn't Work

| Symptom                                             | Cause                                                  |
| --------------------------------------------------- | ------------------------------------------------------ |
| `sandbox.deploy` doesn't return.                    | The sandbox directory isn't on the allowed-paths list. |
| The deploy succeeds, but the connection is refused. | The password was blank.                                |
| The deploy fails on TLS.                            | TLS was requested and `openssl` isn't installed.       |
| `sandbox.stop` fails for a downloaded server.       | The binary isn't on the `PATH`. Use `sandbox.kill`.    |

## A Migration Reports Success but Migrates Nothing

The run was pointed at the output directory of an earlier run. See [migrator Tools](https://mariadb.com/docs/tools/community/mariadb-ai-plugins/mcp-tool-reference/migrator-tools.md#avoiding-a-false-success).

<sub>*This page is licensed: GPLv2*</sub>

{% @marketo/form formId="4316" %}
