Troubleshooting

The plugin does not appear

shire-plugin validate <dir> must print ok.
The manifest id must be unique; reinstalling the same id updates it.
After Install, select the plugin and approve the permissions it declares.
Tick Enabled; the state should move from awaiting_approval/installed to running.
Check the last error and logs in the Plugin Manager.

`-32000 permission denied`

The plugin called a method whose permission is declared but not approved (or not declared at all). The handshake's granted array is the authoritative set. Approve the permission in the manager; a revoked permission fails immediately.

permission denied for ui.setLayout means ui.create was not declared or not approved.

`-32001 rate_limited`

More than 300 calls in one second. Batch UI updates, subscribe to events instead of polling, and avoid calling in a tight loop. A slow consumer also causes outbound event drops (oldest first), not a Shire freeze.

`-32002 not_available`

The Core had no value for the operation (no local player yet, scene transition, no entity list). Retry after a scene load. Do not spin; wait for scene.changed or use a short backoff.

`-32601 method not found`

The method does not exist in this Host. Check api.info.capabilities; the contract test and the SDK may be newer than the installed Shire. Do not assume private offsets.

`-32602 invalid_params`

A coordinate is not finite or out of range, a UI id/type is invalid, a slider min/max is invalid, storage key/value is too large, or the manifest has an invalid field. The error message names the field.

Pipe errors / plugin exits immediately

The Host passes SHIRE_PLUGIN_PIPE, SHIRE_PLUGIN_TOKEN and SHIRE_PLUGIN_ID; a manually launched plugin without them cannot connect.
Synchronous Windows clients that both block on read and write need two connections or overlapped I/O; the C++/Rust SDKs use two. Python polls and the Node/.NET clients are asynchronous.
ERROR_PIPE_BUSY/ERROR_FILE_NOT_FOUND during connection means the Host's next pipe instance is not ready yet; the SDKs retry. If you implement the protocol yourself, retry for a few seconds.
A plugin that exits with a non-zero code is shown as error; read its log and the Plugin Manager's last error.

Interpreter not found

The Host searches PATH for python.exe, node.exe, dotnet.exe or lua.exe. Install the runtime or use an executable package with a bundled binary. The state error includes the language name.

Entrypoint missing after build

Python/Node: the entrypoint is the source file and must exist in the package.
TypeScript: build with shire-plugin build; the manifest entrypoint is out/main.js.
C++/Rust: out/plugin.exe, out/release/plugin.exe.
C#: publish/Plugin.dll after dotnet publish -c Release -o publish.
shire-plugin pack rejects a missing entrypoint; do not ship a skeleton.

Package install fails

.shiremod must be a ZIP with manifest.json at the root.
Shire 1.0 accepts stored entries only; repack deflated packages with shire-plugin pack.
Absolute paths, .., drive colons and oversized entries are rejected.
Check the package SHA and the install message in the manager.

UI does not show

ui.setLayout requires ui.create and a valid array.
Every component except separator needs a unique id.
Select the plugin in the manager; the layout appears under Plugin UI.
Rebuild the layout after a UI event; the Host does not infer state changes.

Open the manager

Press F9 or open Config → Plugins → Open Plugin Manager. The manager is an ImGui window in the same context/theme; it is included in the input capture so clicks do not leak to the game.

Logs

%LOCALAPPDATA%\Shire\plugins\<id>\data\plugin.log
Plugin Manager → selected plugin → Logs
Mock host only: %TEMP%\shire_host_debug.log

When reporting a Host bug, include the API version, the Host build, the plugin manifest, the exact JSON-RPC error and the last log lines. Remove license keys, HWIDs and any personal data from the report.