> ## Documentation Index
> Fetch the complete documentation index at: https://docs.walletwall.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Diagnose WalletWall MCP problems: discovery and stdio configuration, Node.js versions, rejected input, weak or unexpected states, the loopback adapter and WallPrint resolution.

Start by separating two kinds of outcome, because they need different fixes:

* **An error** (`isError: true`, or a JSON-RPC error) means the server could not accept your request:
  a tool name, a resource URI or an input it does not recognise.
* **A weak result** (`NOT_ESTABLISHED`, `UNKNOWN`, `PARTIAL`, `STALE`, `CONFLICTING`) is a successful
  answer about your evidence. It is not a bug, and it should not be retried away.

## Discovery and setup

> [accordion] The tools do not appear in GitHub Copilot
>
> 1. Start a **new** session. A session that was open during the install does not gain the plugin.
> 2. Run `copilot plugin list --json` and check that `walletwall` from marketplace `walletwall` is
>    listed and enabled.
> 3. Run `copilot mcp list` and check that `walletwall` appears among the plugin servers as a local
>    server.
> 4. Check that `node --version` works in the environment Copilot runs in, and reports 22.18 or newer.
> 5. Install with the current names: the marketplace and the plugin are both `walletwall`, so the
>    command is `copilot plugin install walletwall@walletwall`. Historical install records in the
>    repository mention an earlier marketplace name; do not copy it.

> [accordion] Claude Code does not load the plugin
>
> Run `claude --plugin-dir .` from **inside** the `walletwall-claude` clone, or pass the clone's path
> explicitly. The directory must contain `.claude-plugin/plugin.json`, `.mcp.json`,
> `server/walletwall-mcp.mjs` and `node_modules/` (the server loads the SDK and `zod` from it). Check
> that `node` on your `PATH` is 22.18 or newer.

> [accordion] My MCP client starts the server, but it fails or exits
>
> * The command must be `node`, and its single argument the **absolute** path to
>   `walletwall-mcp.mjs`. Relative paths resolve against whatever directory your client starts in.
> * In JSON on Windows, escape backslashes (`C:\\Users\\...`) or use forward slashes.
> * Add no arguments and no environment variables: the server ignores both, and a wrapper script
>   that prints anything to standard output corrupts the stdio protocol.
> * If the process dies, its only message on standard error is the fixed line
>   `walletwall-mcp: fatal error`. Run the same command by hand to see whether `node` itself
>   reports a problem.

> [accordion] Running the server by hand prints nothing and does not exit
>
> That is expected. It is a stdio server: it waits for JSON-RPC on standard input and writes nothing
> until it receives a request. It exits when its input closes, or press Ctrl+C. To exchange messages
> by hand, use the one-liners in the [Quickstart](https://docs.walletwall.org/mcp/quickstart.md).

> [accordion] Which Node.js version do I need?
>
> Node.js **22.18 or newer**. The bundled server (`walletwall-mcp.mjs`) needs no `npm install`. The
> loopback HTTP adapter runs the repository's TypeScript source directly, so it additionally needs
> `npm ci` in the `walletwall-copilot` checkout, and Node.js 22.18 or newer to run `.ts` files.

## Names and URIs

> [accordion] UNKNOWN\_TOOL
>
> Tool names are exact and in snake case: `resolve_asset`, `normalize_observation`,
> `inspect_evidence`, `check_invariants`, `trace_provenance`, `assess_vault_readiness`. GitHub
> Copilot displays them with a `walletwall-` prefix, but the protocol name has none. There is no tool
> for signing, sending, approving, swapping or fetching data, and asking for one returns
> `UNKNOWN_TOOL`.

> [accordion] Unknown resource.
>
> Resource URIs are exact strings: `walletwall://schemas/claims`, not `walletwall://schema/claims`.
> The eleven URIs are listed on [Resources](https://docs.walletwall.org/mcp/resources.md). Asking for resource templates or for
> prompts returns `Method not found`, because the server offers neither; that is expected.

## Rejected input

> [accordion] INVALID\_INPUT: Input failed schema validation.
>
> The `issues` list gives the path and the issue code of each problem, never the value you sent:
>
> | Issue | Typical cause |
> | - | - |
> | `["evaluatedAt"]`, `invalid_type` | A required field is missing |
> | `["bundle","wwepVersion"]`, `invalid_value` | `wwepVersion` is not `"0.1"`; other versions are rejected, not coerced |
> | `[]`, `unrecognized_keys` | An unknown field in the tool arguments; a path such as `["bundle","sources","#"]` points into a bundle record instead. Arguments and records are closed |
> | `["balanceAtomic"]`, `invalid_type` | A JSON number where a string is required, such as `1500000` instead of `"1500000"` |
> | `[]`, `custom` | `resolve_asset` got an `address` without a `chainId`, or neither an address nor a symbol |
>
> Path segments outside WalletWall's vocabulary appear as `*`, and array positions as `#`. Compare
> your input with `walletwall://schemas/evidence` and `walletwall://schemas/claims`. A second message,
> `Input structure is not permitted.` with no issues, means the input is nested more than 12 levels
> deep, holds more than 20,000 values, or has a `constructor` or `prototype` key.

> [accordion] INVALID\_QUANTITY
>
> `normalize_observation` refuses a `balanceAtomic` larger than 2²⁵⁶ − 1, a `decimals` greater than
> 36, and a `VALUE` observation without both `balanceAtomic` and `decimals`. A spelling that is not a
> canonical atomic-unit decimal string at all (a sign, a decimal point, a leading zero) is rejected
> earlier, as `INVALID_INPUT`.

> [accordion] Timestamps are rejected
>
> Use UTC with a `Z` suffix, for example `2026-10-23T12:00:30Z`, optionally with milliseconds. Offsets
> such as `+02:00` and impossible dates are rejected.

## Weak or unexpected results

> [accordion] An assertion is NOT\_ESTABLISHED with INVALID\_SUBJECT, SUBJECT\_MISMATCH, INVALID\_VALUE or VALUE\_MISMATCH
>
> The bundle passed the schema, but the assertion's subject or value does not match its claim type's
> contract or its observation. Read the assertion's `diagnostics`: they name the record checked and
> its required, missing, invalid, unexpected (`*`) and mismatched keys. Rebuild the bundle from
> `walletwall://schemas/claims`, and treat the rebuilt bundle as new input, not as the original.

> [accordion] NOT\_ESTABLISHED with NO\_SOURCE
>
> The assertion cites no observations and has no derivation. Add the observations it rests on and list
> their IDs in `observationIds`. If the assertion also carries a value, `check_invariants` reports
> `INV-01` (`NO_SOURCE_PRESENTED_AS_FACT`): with no source, the value must be `null`.

> [accordion] UNKNOWN with NO\_RESULT
>
> Every observation behind the claim returned `NO_RESULT` or `ERROR`. That is the correct way to
> record a failed or empty lookup from your own provider: it is unknown, not zero. Keep the
> assertion's value `null`; keeping a value reports `INV-01` (`NO_RESULT_AS_VALUE`), or `INV-04` /
> `INV-05` for a zero or `false` value.

> [accordion] PARTIAL when I expected ESTABLISHED
>
> Check the limitations. `NO_AUTHORITATIVE_OBSERVATION` means no observation came from an origin that
> may establish the claim: an asset's identity, for example, needs an `AUTHORITY_ATTESTED` observation
> from an `ISSUER_PUBLICATION` source whose `authorityId` matches the registry. A registry match from
> `resolve_asset` is `PARTIAL` at best. `INSUFFICIENT_INDEPENDENT_CORROBORATION` means fewer
> independence groups support the claim than its policy requires: a single source, or several sources
> in one group.

> [accordion] SUPPORTED with NOT\_FINALIZED or FINALITY\_UNKNOWN
>
> A balance read at an unfinalized block (`NOT_FINALIZED`), or with unknown finality
> (`FINALITY_UNKNOWN`), cannot be `ESTABLISHED`. Use a reading taken at a finalized block.

> [accordion] STALE, or UNKNOWN\_FRESHNESS
>
> Freshness is judged against the `evaluatedAt` you send. A `CURRENT` claim older than its policy's
> maximum age (30 days for asset identity, 120 seconds for a current balance, 300 seconds for a price)
> is `STALE`. An observation timestamped after `evaluatedAt` gives `UNKNOWN_FRESHNESS` with
> `OBSERVATION_FROM_FUTURE`: check the clock and the time zone of the tooling that produced the
> reading.

> [accordion] CONFLICTING
>
> Observations or assertions about the same claim disagree. WalletWall will not choose between them.
> Find out why your sources disagree and gather better evidence; the conflict stays visible until the
> evidence changes.

> [accordion] Readiness is NOT\_ESTABLISHED or CRITERIA\_NOT\_MET
>
> Read the `criteria`. `INDETERMINATE` criteria give `NOT_ESTABLISHED`; any `NOT_MET` gives
> `CRITERIA_NOT_MET`. If every criterion says `REQUIRED_INPUT_ASSERTION_MISSING_OR_WRONG_CLAIM_TYPE`,
> `identityAssertionId` and `balanceAssertionId` are missing or swapped: the first must name an
> `ASSET_IDENTITY` assertion and the second a `TOKEN_BALANCE_AT_BLOCK` assertion.

> [accordion] The same address is treated as two subjects
>
> Conflict grouping and supersession compare subjects exactly, so `0xA0b8…` and `0xa0b8…` are two
> subjects. Use lowercase addresses throughout; `normalize_observation` lowercases them for you.

> [accordion] My data provider failed or returned something odd
>
> WalletWall MCP never calls your provider, so provider and network failures happen in your own
> retrieval tooling, before WalletWall is involved. Record a failed lookup as an observation with
> `NO_RESULT` or `ERROR` rather than leaving it out or writing zero, and record how each reading
> arrived in `transport.retrievedVia`.

## Loopback HTTP adapter

> [accordion] Nothing answers on the port
>
> Check the line the adapter printed at start-up: it names the actual address and port. Then:
>
> ```bash theme={null}
> curl -s http://127.0.0.1:8787/health
> ```
>
> `{"status":"ok"}` means the adapter is up. If the adapter exited immediately with
> `walletwall-mcp-http: fatal error`, the port may be in use, the port value may be invalid, or
> `--host` was given something other than `127.0.0.1` or `0.0.0.0`.

> [accordion] 400, 403, 405, 413, 414 or 415
>
> | Status | Cause |
> | - | - |
> | `400` | A body that is not valid JSON, or a malformed `Content-Length` header |
> | `403` | The request carried an `Origin` other than `http://127.0.0.1:<port>` or `http://localhost:<port>`; with `--host 0.0.0.0`, any `Origin` is refused |
> | `405` | A method other than `POST` on `/mcp` |
> | `413` | A body larger than 512 KiB |
> | `414` | A URL longer than 256 characters |
> | `415` | A `Content-Type` other than `application/json` |

> [accordion] /health works, but /mcp responses are malformed
>
> If `/health` answers correctly but MCP calls fail with errors about an invalid chunked response,
> something between the client and the adapter is rewriting local HTTP traffic. Security software
> that inspects HTTP connections can do this even on `127.0.0.1`. Try from a different environment
> (for example WSL on Windows), or exclude the loopback adapter from that inspection.

## WallPrint resolution

> [accordion] Record unavailable (UNAVAILABLE)
>
> No record with that ID is published at the resolver. This is not a judgement on the record: it was
> never published there, or the reference was copied wrongly. Published records are listed at
> `https://walletwall.org/wallprint/index.json`.

> [accordion] DIGEST\_MISMATCH, MALFORMED\_REFERENCE or UNSUPPORTED\_VERSION
>
> * `DIGEST_MISMATCH`: the record is published under other bytes than the digest in your reference.
>   Every digest is printed, and the published version is offered as a link. It is an integrity
>   finding, not an accusation of forgery.
> * `MALFORMED_REFERENCE`: the reference text was altered or truncated. References have exactly one
>   valid spelling; copy them exactly.
> * `UNSUPPORTED_VERSION`: only reference and WallPrint version `0.1` resolve today.

> [accordion] UNREACHABLE
>
> The page could not read the store. It says nothing about the record. Reload, and check that the
> page is served from `walletwall.org`.

## Still stuck?

Open an issue on [`Wallet-Wall/walletwall-copilot`](https://github.com/Wallet-Wall/walletwall-copilot)
with the tool or resource involved, the error code and `issues`, and the output of
`walletwall://conformance/version`. Use synthetic values only, and never include a real wallet address,
key or credential. For security problems, follow [Privacy & Security](https://docs.walletwall.org/mcp/privacy-security.md) instead.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.