Client and server troubleshooting

Use this page when the client cannot connect, the wrong transport starts, runtime status is unclear, or local storage prevents Frigg from serving.

Client cannot connect to HTTP

Start the shared service and keep it running:

frigg serve

Confirm the client URL includes /mcp:

http://127.0.0.1:37444/mcp

If the port is already in use, choose another one for both the server and client:

frigg serve --mcp-http-port 4000

There is no FRIGG_MCP_HTTP_PORT environment variable.

Client launches the wrong transport

These invocations have different contracts:

Invocation	Transport
frigg	stdio
frigg --workspace-root /repo	stdio
frigg serve	HTTP on the default port
frigg --mcp-http-port 4000	HTTP on port 4000

Do not put frigg serve in a stdio client configuration. Do not point an HTTP client at a process launched without serve or --mcp-http-port.

Remote HTTP is refused

A non-loopback bind requires all three parts:

frigg serve \
  --mcp-http-host 0.0.0.0 \
  --allow-remote-http \
  --mcp-http-auth-token <TOKEN>

Common failures:

Error or status	Cause	Fix
Refuses non-loopback bind	--allow-remote-http is missing	Add the flag and a token.
Requires auth token	Token is missing	Set the flag or FRIGG_MCP_HTTP_AUTH_TOKEN.
Token must not be blank	Token is empty or whitespace	Supply a nonblank value.
HTTP 401	Authorization is missing or invalid	Send Authorization: Bearer <TOKEN>.
HTTP 403 with unauthorized host/origin	Client authority does not match a specific bind	Use the configured host and port in the client URL.

Bearer authentication covers the MCP and routing-stats endpoints.

Frigg is absent from the client’s tools

1. Confirm the service or stdio process is running.
2. Reload the client after changing MCP configuration.
3. Inspect the client’s live tool list; configuration files on disk do not prove that the client registered Frigg.
4. If a parent agent has Frigg but a subagent does not, check the host’s MCP inheritance or registration behavior.

This is a client/harness registration problem when no Frigg tools are callable. It is not a search-ranking problem.

Repository status is unclear

There is no frigg status CLI command. Call the MCP workspace tool and inspect:

• the session default and adopted repositories;
• snapshot and continuous freshness;
• post-edit recovery strategy;
• changed paths and per-tool capabilities;
• active runtime tasks and watch state.

frigg stats reports process-local routing counters, not repository health.

Routing stats are disabled or unreachable

Enable counters before the HTTP process starts:

FRIGG_ROUTING_STATS=1 frigg serve
frigg stats

If the command cannot connect, check that it uses the server’s HTTP flags and token:

frigg stats \
  --mcp-http-port 4000 \
  --mcp-http-auth-token <TOKEN>

frigg stats --json returns the live /stats/routing snapshot. Recording is process-local and resets when the server restarts.

Startup reports missing storage

A serving process with configured roots requires initialized storage. From each repository root, run:

frigg init
frigg index

init creates the current database schema without scanning source. index performs the source refresh.

Storage repair fails

Frigg automatically attempts one repair of regenerable sqlite-vec projection invariants during init, index, and serving startup. If the database has an incompatible schema version or is missing required relational tables, automatic repair and hidden repair-storage cannot migrate it.

Rebuild the regenerable database:

rm -f .frigg/storage.sqlite3
frigg index

Use hidden frigg repair-storage only when maintainer guidance specifically calls for rebuilding the derived vector projection from existing semantic rows. It does not re-embed or reindex source.

Database is locked

Frigg waits 30000 milliseconds by default for SQLite writer contention. Prefer one shared HTTP service instead of several stdio processes writing the same repository. When contention is expected, increase the positive timeout:

FRIGG_SQLITE_BUSY_TIMEOUT_MS=60000 frigg serve

For a one-off indexing job, stop duplicate Frigg processes or temporarily disable watch rather than creating another storage directory.

Output is missing or unexpected

• --quiet suppresses normal result, warning, and progress events; errors still appear on stderr.
• --verbose adds progress and per-repository detail.
• Combining --quiet and --verbose is an error.
• Interactive terminals render human blocks on stderr.
• Non-interactive normal output emits stable summaries on stdout.
• TERM=dumb disables TUI output; NO_COLOR disables color.
• Stdio MCP reserves stdout for protocol frames.

Source Anchors

• ../frigg/README.md
• ../frigg/crates/cli/src/cli_args.rs
• ../frigg/crates/cli/src/cli_dispatch.rs
• ../frigg/crates/cli/src/http_runtime.rs
• ../frigg/crates/cli/src/cli_runtime/output.rs
• ../frigg/crates/cli/src/cli_runtime/startup_gates.rs
• ../frigg/crates/cli/src/cli_runtime/commands/stats.rs
• ../frigg/crates/cli/src/cli_runtime/commands/storage.rs
• ../frigg/crates/cli/src/storage/lifecycle.rs
• ../frigg/crates/cli/src/storage/db_runtime.rs