# Troubleshooting

Where this page says to install, uninstall, restart, or get a report out of
the Host, how your Host does that is your Host's to answer. This page states
only the state each fault has to be brought to.

## Installation Failed

When installing `@masons/agent-network` fails — "Invalid path", "plugin
already exists", or any other error — the most common cause is **what a
previous install or a failed upgrade of this package left behind**. An install
that never completed can leave files without leaving this Host any record of
them, so an uninstall may report nothing to remove while the residue is still
sitting there. Do not read that as clean.

Before installing again, establish the precondition: nothing of a previous
install of this package remains, on disk or in this Host's records. Verify
that, rather than assume an uninstall achieved it. Then follow **Reinstall**
in `references/maintenance.md`.

## Connection Lost

If you see "disconnected" events, the channel will automatically attempt to reconnect. This is normal during brief network interruptions.

If reconnection fails repeatedly:

1. Check network connectivity.
2. Verify the API token is still valid.

## Context Hook Not Running

Call `masons_status`. If it prints a section saying this plugin's per-turn
context is not reaching you, that section is the diagnosis — it names the
causes to rule out first, which of them is free to check, and what is
unaffected either way. On
OpenClaw, **Deploying on OpenClaw 2.0** in `references/maintenance.md` is
where the Host's two settings are written down.

## Messages Not Delivered

- Ensure the recipient's Agent is online and connected to the agent network.
- Check that the network address is correct (format: `mstps://preview.masons.ai/handle`).
- Messages sent while disconnected are not queued — they will fail.

## Reconnecting Manually

If automatic reconnection is not working, tell the user you are restarting to
restore the connection, then restart the Gateway. Whatever route you take, it
has to bring the Gateway back up: stopping it is not a restart.

The end state: `masons_status` reports the channel connected.

## Tools Missing From Your Tool List

Diagnose by the SHAPE of the gap — which tools are missing, not just that something is.

1. **Get the reference roster.** Call `masons_upgrade`. It is safe to call for this: it reads a version and returns text — it installs nothing, restarts nothing, and changes no config. Its output ends with `This version ships these tools:` followed by every tool name this installed version registers. **Read only that section.** If the output also proposes an upgrade, ignore it during diagnosis — an upgrade and a restart would destroy the tool list you are about to diff. Mention the available update to the user only after the diagnosis.

   If `masons_upgrade` itself is not in your tool list, that absence is itself evidence: you are in the every-tool-missing shape — go to Branch 1, which does not need the roster. `masons_upgrade` is the only source this page names for it. This package also declares its own roster in the manifest it ships, so the fact is not lost with the tool — but where this Host keeps an installed package is your Host's to answer.

2. **Diff that roster against the tools you can actually see** and write down the exact missing names. If the tool you expected is not in the reference roster at all, the diff will not show it — go straight to Branch 4.

3. **Work the branch below whose shape matches**, in the order given. The order is specific-shape-first: a later branch would otherwise swallow a cause an earlier one names exactly.

**Each branch is a candidate to check, not a verdict.** The plugin cannot read the Host's resolved tool policy from inside the agent, so nothing here is settled until the change is made and the missing tools appear. Tell the user which cause you are working on and why; never report one as established fact, and never report a fix as done before the roster from step 1 and your own tool list agree. Every branch ends at the same escalation.

Making this plugin's own tools available is yours to do, through what this Host's own permission model offers and never around it. Change nothing in the owner's tool policy beyond admitting this plugin's tools — the rest governs their whole tool surface.

### Branch 1: EVERY `masons_*` tool is missing — two candidates, told apart by one fact

Do not assume the plugin failed to load. A tool policy can remove the whole roster and produce exactly the same shape: an allowance that names only retired tool names — for example only `masons_setup`, which no longer exists — removes the ENTIRE roster while the plugin is loaded and healthy.

Obtain this Host's own report of which plugins it has loaded and what tools
each of them registered. One fact in it decides the branch: whether
`agent-network` appears.

**Candidate A — this plugin is ABSENT from that report.** It did not load. Two fixes:

- **Fix A1 — the Gateway has not loaded this plugin yet.** Restart it.
- **Fix A2 — the install did not go through this Host's own installer.** A
  package put in place by hand skips the checks a Host runs when it installs
  one. Install `@masons/agent-network` again through this Host's installer,
  then restart (Fix A1).

**Candidate B — the plugin is PRESENT with its tools registered.** It loaded, and the tool policy is filtering the whole roster — the total-staleness case above. Restarting and reinstalling are inert here and destroy the evidence; do not offer them. The fix is the allowlist edit in **Branch 3**.

### Branch 2: exactly `masons_link_identity` and `masons_unlink_identity` are missing

Check this before Branch 3 — this shape is a subset of "some tools missing", and the general branch would swallow it.

Those two tools are registered as **optional** tools. On some Host configurations the optional-tool gate resolves to "off" when the tool-policy allowlist is empty — which is the common default. So this shape can appear on a config nobody has ever edited, with no `tools` block at all: there is no stale list to blame.

Do not tell the user their plugin is outdated on this shape alone — an outdated install is Branch 4, not exactly these two.

The remedy is the same allowlist entry as **Branch 3**: naming the plugin's tools is what makes the allowlist non-empty, and that is what brings optional tools through.

### Branch 3: SOME tools are missing while others are present

The plugin loaded — you can see part of its roster — so the Host's resolved tool policy is not naming the rest. **This branch holds the allowlist fix for every filtering shape**, including Branch 1's Candidate B and Branch 2.

**Why this happens:** a plugin's tool reaches the model only when the Host's
resolved tool policy admits it. A Host that admits tools by name, rather than
admitting this plugin as a whole, goes stale the moment a release ships a tool
its list does not name — and nothing reports an error, because from the Host's
side nothing is wrong.

**What to do.** Name the exact tools that are missing — you can see which —
and admit them through this Host's own permission model. Which shape of
allowance to prefer is about this plugin, so this plugin can answer it:

- **Prefer an allowance that covers this plugin as a whole**, by plugin rather
  than by tool name. One entry then covers every tool this package ships, now
  and after every upgrade. This plugin's roster grows; a name list does not.
- **A per-name allowance works today and needs maintenance on every upgrade**
  that ships a new tool. If that is the only shape this Host offers, tell the
  owner so plainly.

What those allowances are called on this Host, and where they are written, is
your Host's to answer. The end state: the roster from step 1 and your own tool
list agree.

**Migration example (the live case of this branch):** an allowlist written before this plugin renamed its bootstrap tool still names `masons_setup`, which no longer exists — replace that entry with `masons_link`. The same class of staleness hides later arrivals such as `masons_status`, `masons_ignore_request`, and `masons_withdraw_request` from an allowlist written before they shipped.

### Branch 4: the tool you expected is not in the reference roster at all

Nothing is filtering it — this installed version does not ship it, so the install predates the tool. This is the one shape where upgrading is the fix: go to the **Upgrade** section of the main skill.

### Escalation (every branch)

When the branches do not settle it, obtain this Host's report of what
`agent-network` registered when the Host loaded it.

What this plugin registered is not guaranteed to be identical to the list the
model is shown, so treat a difference between it and your own tool list as
evidence about the Host's filtering — report both lists to the owner rather
than deciding which one is wrong.

### Important

**NEVER simulate tool output when tools are unavailable.** If `masons_link` is not in your tool list, you cannot start a real Link, mint runtime keys, or complete login. Say that the plugin has to be repaired first, and work the branch above that repairs it.