Troubleshooting

This page covers the common startup problems and their fixes.

Collect diagnostics

Run these commands before reporting a setup problem:

truenorth-mcp --version
truenorth-mcp --check-config

--check-config returns a JSON report and exits nonzero when a required check fails. It reports an actionable fix for a missing repository root, invalid layout, unreadable feature configuration, missing verify command, or invalid gate environment name. It reads configuration only. It does not start the MCP server, mutate the workspace, run the verify command, or print configured command or environment values.

The server cannot resolve the repository root

The runtime resolves the repository root by looking for a directory that contains .agent/, specs/, and skills/. A run from a subdirectory, or from a directory without all three markers, fails to resolve the root and exits with an error like this:

no valid repository root among the evaluated candidates. A valid root must directly
contain a `.agent/`, a `specs/`, and a `skills/` directory. Set the `TRUENORTH_ROOT`
environment variable to the repository root, or run the server from inside the repository.

To fix it, do one of the following:

• Run the client from the repository root.
• Set TRUENORTH_ROOT to the repository root in the client config.

{
  "mcpServers": {
    "truenorth": {
      "command": "npx",
      "args": ["truenorth-mcp"],
      "env": { "TRUENORTH_ROOT": "/absolute/path/to/repo" }
    }
  }
}

The layout contract is incomplete

At startup the runtime validates the .agent/ layout contract. A missing required entry logs a warning that names the absent path, and the runtime keeps serving on the last valid state rather than crashing.

To fix it, add the named entry. The full set of required entries is on The .agent workspace. For a new project, run truenorth_scaffold_project to seed the complete tree.

A mutating tool reports writer_lease_conflict

Another TrueNorth server owns mutation rights for the same worktree. Existing resource reads remain available. A mounted MCP connection stays bound to the repository root it selected at startup, so creating a worktree does not retarget that connection.

Use the client connected to the owner, close the owner and retry, or configure a separate MCP server connection for the other worktree:

{
  "mcpServers": {
    "truenorth-feature": {
      "command": "npx",
      "args": ["-y", "truenorth-mcp"],
      "env": {
        "TRUENORTH_ROOT": "/absolute/path/to/feature-worktree"
      }
    }
  }
}

Select that connection before you invoke a mutating tool. See the install guide for client-specific configuration.

The error identifies .agent/runtime/writer.lock and can include the owner process id. Do not delete the file. It is a persistent rendezvous path, while the operating-system lock is released automatically when the owner exits or crashes. A running contender retries the lease on its next mutation. Moving the worktree to a shared network filesystem is not a supported coordination mechanism. See the canonical operating model.

A mutating tool reports stale_write_conflict

A file changed after the tool read it. The runtime left the external content unchanged. Read the current cockpit state, reconcile the edit, and retry the tool.

An ontology tool or resource is missing

When the ontology feature is disabled, the two ontology tools and the truenorth://ontology resource are absent by design. A read of the ontology URI is an unknown resource. This is not a fault. To enable the surface, set features.ontology: true in .agent/config/rules.yml. See The ontology feature.

A resource read returns an error

A parse or validation failure on a backing file returns a resource read error that names the file and the cause. The runtime retains the last good content and keeps serving the other resources. Fix the YAML in the named file. The watcher revalidates on the next edit.

A verify gate is not configured or fails

truenorth_verify_gate accepts only a lifecycle phase. It runs the operator-configured project command and passes only when the server observes exit code 0. Set TRUENORTH_VERIFY_CMD in the MCP client environment. If the command needs a non-default environment variable, add its name to TRUENORTH_GATE_ENV_ALLOWLIST. Run truenorth-mcp --check-config, then restart the client. Credential-like and TRUENORTH_* names are rejected. See Install and connect for the complete configuration.

A non-zero exit returns a bounded, line-aware diagnostic excerpt with remediation hints. The error data reports whether the excerpt was truncated and its captured and returned byte counts. When the excerpt is truncated, rerun the configured gate locally in the repository to inspect the complete command output. Exact inherited environment values are redacted from returned stderr. Do not send mode or test_evidence; both fields are rejected.