Troubleshooting

Cargo build fails with missing wasm32-wasi target

You see an error like error[E0463]: can't find crate for 'std' or the 'wasm32-wasi' target may not be installed when building traverse-expedition-wasm.

Add the wasm32-wasi target to your Rust toolchain.

Then retry the build. If you are on a nightly toolchain, also run rustup update to make sure the target is available for your current channel.

bundle inspect returns error about missing manifest

Running bundle inspect prints something like error: manifest not found at path or no such file or directory.

The path must point to the bundle directory, not to the manifest file itself. The command expects a directory that contains a manifest.json.

If the directory exists but still fails, check that manifest.json is present inside it and that it is valid JSON.

Browser adapter starts but UI cannot connect

The adapter process is running but the browser app shows a connection error or requests time out. This is usually a port conflict or a CORS issue.

Check that nothing else is listening on port 4174 and that the adapter is bound to the right address.

If the port is taken by another process, start the adapter on a different port with --bind 127.0.0.1:4175 and update your React app's base URL to match.

React demo shows blank page

You open the React demo URL and the page is blank. No visible error. Check the browser console first — usually this is a Node version mismatch or a startup order problem.

Node.js 18 or later is required. Start the browser adapter before starting the React server.

Capability not found in registry

The runtime returns capability not found or the trace shows the discovery state failing. The bundle was not loaded, or the bundle path is wrong.

Verify the bundle path and reload it. Use bundle inspect to confirm the capability ID matches what you are requesting.

Contract validation fails on execution

The runtime rejects a request with a validation error before execution even starts. This usually means the inputs do not match the contract's input schema, or a precondition failed.

Read the validation error in the trace. It includes the failing field and the expected type.

Fix the input payload to match the contract's inputs schema. Check the contract file for the required fields and their types.

MCP server not responding to tools/list

Your MCP client sends a tools/list request and gets no response, or the connection hangs. The MCP server uses stdio, so misconfigured client wiring is the most common cause.

Check your MCP client config. The command must point to the compiled traverse-mcp binary and must not have extra shell wrapping that intercepts stdin/stdout.

You can also test the server manually by piping a JSON-RPC request to stdin.

Test suite fails with coverage below 100%

CI blocks your PR with a coverage gate failure. Traverse enforces 100% test coverage on all business logic paths. Every new code path needs a test.

Run coverage locally to find the uncovered lines before pushing.

Open the HTML report to find the exact uncovered lines. Add tests for each uncovered path. Error branches and early returns both need coverage.

Spec alignment gate fails in CI

CI rejects your PR because a spec alignment check failed. Traverse requires every code change to be backed by an approved governing spec. New behavior without a spec is not accepted.

Follow this process for any change that introduces new runtime behavior.

1. Open a spec proposal in the specs/ directory following the existing format.
2. Get the spec reviewed and merged with the approved label.
3. Reference the spec ID in your implementation PR using the standard annotation.
4. The CI gate reads spec references from code annotations and validates each one against the approved spec list.

If you are fixing a bug within already-specified behavior, the gate should pass automatically. If the gate blocks a bug fix, it means the existing spec does not cover the edge case and needs an update.