Troubleshooting

Start with status, then repair deliberately.

Most Link issues are local path, stale graph, MCP Python, raw safety, or validation problems. The commands below are safe first checks.

Is Link Ready?

lnk health
lnk status --validate
lnk doctor
lnk next

If link is not on your PATH, run from the source checkout with python3 link.py, or add ~/.local/bin to your shell path.

MCP Is Not Visible

lnk verify-mcp
python3 -m pip index versions link-mcp

Restart the MCP client after changing its config. If your installer printed a venv Python path, use that exact path in the MCP config.

You do not need lnk serve or serve.py running for MCP. The web viewer is separate from the MCP server.

Ingest Is Blocked

lnk ingest-status

Blocked ingest usually means a raw source has secret-looking values, cannot be read safely, or source representation counts may be incomplete. Redact or fix the local file, then ask the agent to ingest again.

Interrupted Writes

lnk operations
lnk validate
lnk doctor --fix

If a memory write was interrupted, Link leaves a marker under wiki/.link-operations/. Inspect it before deleting anything manually, then validate the wiki and repair generated indexes if needed.

Graph Is Stale

lnk rebuild-index
lnk rebuild-backlinks
lnk validate

Run this after manual Obsidian edits, hand-written wikilinks, or a failed ingest.

Demo Looks Stale

link-demo/ is generated local output and is ignored by git. If it was created with an older Link version, regenerate it:

python3 link.py demo link-demo --force
python3 link.py health link-demo
python3 link.py query "why does Link help agents?" link-demo --budget small

The current generated demo should include three raw sources, source-backed wiki pages, one starter memory, one exploration, current backlinks, and schema v1.

The Wiki Feels Slow

lnk benchmark "agent memory"
lnk graph-summary "agent memory" --limit 40 --depth 1

Large graph views intentionally open bounded first. Use type filters, node search, depth controls, and explicit all-data loading only when you need search or filtering across every page.

If lnk health or lnk benchmark shows low persistent-cache reuse after repeated runs, inspect recently edited pages or generated files that are changing on every request.

From a source checkout, use the synthetic smoke script when you want local scale evidence without touching your real wiki:

python3 scripts/smoke_large_wiki.py --pages 10000

pip Is Blocked By Homebrew Python

If pip reports externally-managed-environment, avoid forcing packages into Homebrew Python. Use a dedicated venv:

python3 -m venv ~/.link-mcp-venv
~/.link-mcp-venv/bin/python -m pip install --upgrade pip link-mcp

The current installers do this automatically when needed.