# Troubleshooting

Start with the extension's Console in Grove Manager. It combines `console` output, `grove.log` messages, uncaught JavaScript errors, blocked navigation and sandbox failures, and WebContent termination notices.

When asking for help, include the Mango version, `manifest.json`, the relevant bridge call, and the smallest safe Console excerpt. Remove tokens, message text, local paths, and other private data.

## The package will not load

Check these causes in order:

- `manifest.json` is missing from the selected directory;
- `grove` is not the integer `1`;
- `id` has no dot or starts or ends with a dot;
- a capability string is misspelled or undocumented;
- `entry`, `settings`, `icon`, `readme`, or a screenshot does not exist;
- a path is absolute, escapes with `..`, resolves through a symlink outside the package, or names a directory;
- the README is not Markdown or a screenshot is not PNG, JPEG, or WebP;
- an upload contribution is not a headless Root, lacks `uploads.provide`, duplicates an identifier, or has an invalid limit.

For a built project, inspect the final output directory or `.grove` archive rather than the source tree. Vite and similar tools may copy `manifest.json` but omit files that are not part of their public/static asset pipeline.

## An event never arrives

Verify all three parts of the route:

1. the manifest requests the documented capability;
2. the user accepted that capability for the installed package;
3. the running instance is bound to the channel, query, or server scope where the event occurs.

Application-scoped Roots intentionally receive no IRC event stream.

Ordinary `message` delivery is live-only. A Root that starts after bouncer history arrives should not expect those historical rows as new `message` events.

Reserved capability names such as `server.events` and `identity` do not have API 1 events or getters. `channel.members` and `channel.metadata` are implemented through the retained `channelSnapshots` event.

## A bridge call does nothing

Most Grove methods are fire-and-forget; a native rejection appears in the Console rather than as a JavaScript exception. Confirm:

- the matching capability is granted;
- the call is valid for the surface and scope;
- a targeted send uses the correct query permission;
- a server-scoped `{ channel }` send has `network.send`, names one strict channel, and the network has a confirmed matching join;
- a registered identifier was declared and has a valid shape;
- a composer method is called only by an exclusive composer utility;
- the Root has not stopped or lost its grant.

Built-in slash commands cannot be overridden. Command collisions between extensions are first-wins.

## Fetch or WebSocket is blocked

The exact scheme and host must appear in `hostPermissions`. `https://api.example.com` does not grant `wss://api.example.com`, a sibling subdomain, or cleartext access. The only narrow wildcard is a complete leftmost label such as `https://*.example.com`; it matches one direct subdomain, not the apex or a deeper name. Other partial wildcards are not supported.

A settings page always has an empty network allow-list. Save configuration there, then let the running extension perform the request.

Navigation, `window.open`, frames, forms, WebRTC, and undeclared beacons are intentionally blocked and are not supported network strategies.

## Persistent state disappears or leaks across scopes

Request and obtain `storage` for persistent Web storage. Without it, local storage is ephemeral.

API 1 shares the WebKit store between instances of the same extension identifier. Include `grove.info.networkID`, scope kind, and target in keys when data must be per-network or per-buffer.

Use `storage.secure` and `grove.secrets` for credentials. The default secret namespace is per network; `grove.secrets.application` is shared across network instances.

## An upload provider is unavailable

Confirm that:

- the installed manifest declares an upload provider;
- the extension is an exclusive headless Root with `scope: "application"` for one destination shared across networks, or `scope: "server"` for deliberately per-network configuration;
- `uploads.provide` is granted;
- the Root is running for that IRC session, or the application-scoped Root has been started and mirrored into it;
- JavaScript called `grove.uploads.register` with the exact declared identifier;
- the selected file matches image and size restrictions;
- endpoint configuration is present and its origin is allowed.

File reads must be positive, inside the file, and no larger than 1 MiB. Return an `http` or `https` URL. A TUS upload location is not necessarily a recipient-accessible download URL.

## A filter behaves unexpectedly

Filters are ordered and may see changes made by an earlier filter. Use `wireText` for what IRC will receive and `displayText` for what Mango will show. Avoid the legacy string replacement form when those values may differ.

A timeout, thrown error, WebContent crash, or invalid result fails open and allows the message. Only a valid explicit `deny` drops it. Inspect the Console and keep filter work bounded so it can complete before the native timeout.

## The extension stops in the background

Grove Roots are client-side WebKit runtimes, not server workers. Listen for lifecycle events, reconnect sockets after `foreground` or `pulse`, persist necessary state, and accept that iOS suspension stops reliable execution. Move truly always-on work to a backend and keep the Grove extension as its capability-scoped client.