FAQ and Troubleshooting

Common issues and solutions when running Wanaku.

"Address already in use" on startup

Something else is using port 8081 or 8080. Check with:

lsof -ti :8081
lsof -ti :8080

Kill the process, or change the management listen address via WANAKU_MGMT_LISTEN. The MCP listener address is defined in the pipeline config — use a custom config file with --pipeline-config to override it.

Empty JSON-RPC response from MCP endpoint

Check that:

• The MCP filter has on_invalid: continue in the pipeline config
• You send valid JSON-RPC with "jsonrpc": "2.0", "method", and "id".
• The URL path matches /{namespace}/mcp. Use /default/mcp for the default namespace.

Enable trace logs to see what the filters are doing:

RUST_LOG=wanaku_filters=trace wanaku-server

Tools do not appear in /default/mcp but appear in wanaku tools list

Check the namespace. Tools registered with namespace: "finance" appear only in /finance/mcp. They do not appear in /default/mcp.

# List tools in the default namespace
wanaku tools list --no-auth

# Query the finance namespace via MCP
curl -X POST http://localhost:8081/finance/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'

Tool calls time out

MCP forward calls have a connection timeout. If the upstream MCP server takes too long, verify that it is reachable and responds:

curl -s http://your-upstream-mcp:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'

LLM-based features (evaluators, inference proxy) do not work

Verify:

• The LLM endpoint is reachable (curl http://localhost:11434/v1/models)
• WANAKU_INFERENCE_UPSTREAM is set correctly for the inference proxy (port 8083)
• Evaluator LLM connections are defined under llm_connections in wanaku.yaml

Server crashes with "thread 'main' panicked"

Wanaku denies unsafe_code, unwrap_used, expect_used, and panic at the crate level. A panic means a logic bug. File an issue at github.com/wanaku-ai/wanaku/issues with the stack trace and steps to reproduce.

CLI returns authentication errors

When running against a Wanaku server without authentication enabled, use the --no-auth flag:

wanaku tools list --no-auth

When authentication is enabled, authenticate first or pass a token:

# Pass a token directly
wanaku tools list --host http://localhost:4180 --token $TOKEN

# Or use the CLI's built-in auth
wanaku auth login --api-token <your-token>
wanaku tools list

Registry data lost on restart

File persistence is enabled by default. Wanaku uses $HOME/.wanaku/server/registry.json. Set a different path when the default location is not suitable:

export WANAKU_PERSIST_BACKEND=file
export WANAKU_PERSIST_PATH=/data/registry
wanaku-server

On startup, the server loads registry.json from WANAKU_PERSIST_PATH. After each registry change, a background writer saves a full snapshot. On an orderly shutdown (SIGTERM, SIGINT), the server waits up to 10 seconds for a pending snapshot.

NOTE

If the process stops because of SIGKILL or an out-of-memory error, changes since the latest completed snapshot are lost. File persistence supports one writer. See Registry Persistence.

To disable persistence, set WANAKU_PERSIST_BACKEND=none.

Server does not start

The server prints fatal: <reason> and stops. These are common reasons:

Message or log	Cause	Action
invalid governance configuration	The governance section has an unknown key or a value that is not valid.	Correct the section. See Governance Posture.
evaluator startup failed: configuration_invalid	An evaluator definition is not valid. For example, it uses the removed llm: key instead of engine:, names an unknown connection, or has a processor.path file that does not exist or does not compile. A relative path resolves against the working directory.	Read the startup evaluator configuration rejected or failed to parse evaluators config log line for the details. Correct the evaluator. In a source tree, build the example actions into actions/dist/. See Evaluator Engine.
evaluator startup failed: connection_configuration_invalid	A connection entry is not valid, or an env: reference names a variable that is not set. Wanaku resolves every connection, also connections that no evaluator uses.	Set the variable, or remove the connection.
unknown keys in wanaku configuration: <keys>	wanaku.yaml has a key that the server does not read. The message gives the path of each key, for example evaluators.0.trigger.namepsace.	Correct or remove each key. See the list of top-level keys.
invalid wanaku configuration YAML	The wanaku.yaml file is not valid YAML.	Correct the YAML syntax.
wanaku config not found, using defaults (warning, the server starts)	The --wanaku-config file does not exist. The default is wanaku.yaml in the working directory.	Correct the path. The server does not stop for a missing file, also when you give the path explicitly.

Any one invalid evaluator rejects the complete evaluator configuration. To start the server with an invalid evaluator runtime that blocks governed requests, set evaluator_startup_failure: deny. See Evaluator governance startup.

A configuration key has no effect

The server rejects unknown keys in wanaku.yaml. A misspelled key stops startup and does not have this symptom. The server does not reject unknown environment variable names. If a setting has no effect, check the spelling of its environment variable. See An environment variable has no effect.

Tool calls fail with -32003

The action-policy filter denied the request. With the default no_match: deny and no action policy, the filter denies every tools/call, resources/read, and prompts/get. The action-policy filter and the evaluator filter apply no_match independently. A governed request needs an action-policy rule that allows it and an evaluator that matches it, or a no_match: allow override for the namespace. See Governance Posture.

An environment variable has no effect

The server does not reject unknown environment variable names. A misspelled name has no effect, and the server uses the default value. Enable trace logs to verify the values that the server uses.

Evaluators

"WASM component failed to compile"

Cause: The .wasm file is invalid or does not match the WIT interface.

Fix:

1. Verify you compiled with the correct --wit path and --world-name evaluator-action
2. Check that your imports match the WIT exactly (namespace, function names, signatures)
3. For JavaScript, use jco componentize. Do not use jco transpile.
4. For Rust, verify cargo.toml has the correct [package.metadata.component.target] path and world

"Evaluator did not trigger"

Cause: The trigger does not match the request.

Fix:

1. Check server logs for evaluator filter trace messages — they show what the filter sees
2. Verify trigger.method matches mcp.method metadata (e.g., tools/call not tool/call)
3. If you use trigger.namespace, verify that the request URL uses /{namespace}/mcp. A bare /mcp path is invalid.

Enable trace logs: RUST_LOG=wanaku_feature_evaluator=trace

"LLM returned invalid output"

Cause: The LLM did not follow the prompt format.

Fix:

1. Add result_schema to the LLM configuration. The host validates the LLM output. If the output does not match, the host retries once with a correction prompt:

   engine:
     type: llm
     result_schema:
       type: object
       properties:
         level: { type: string, enum: ["green", "yellow", "red"] }
         reason: { type: string }
       required: ["level", "reason"]

2. Use verifyLlmResult() in your WASM script — even with host-side validation, the guest can double-check and call rejectMalformed() instead of silently proceeding with bad data:

   const validated = verifyLlmResult(ctx.llmResult);
   if (validated.tag === 'err') {
     rejectMalformed(`Cannot assess: ${validated.val}`);
     return;
   }

3. Make your prompt more explicit: "Respond with ONLY a JSON object, no other text"

4. Use a smaller, faster model for classification tasks — they need less context

"WASM action did nothing"

Cause: The action did not call a response function. The default pass() action applied.

Fix: Call block(), warn(), filterTools(), or setMetadata() in the action. To pass explicitly, call pass(). This call is optional.

"Hot-reload did not apply my WASM changes"

Cause: You changed the WASM file but did not call PUT /api/v1/evaluators.

Fix: The engine only compiles WASM at hot-reload time. After building a new .wasm file, trigger a reload:

curl -X PUT http://localhost:8080/api/v1/evaluators \
  -H "Content-Type: application/json" \
  -d @current-config.json

This re-compiles all WASM files referenced in the config.

Debugging

Enable trace logs to see all filter decisions, metadata reads/writes, and registry operations:

RUST_LOG=trace wanaku-server

For filter-specific logs only:

RUST_LOG=wanaku_filters=trace wanaku-server