Troubleshooting
What to do when Link Harness doesn't answer, or answers wrong.
macOS: "Operation not permitted" before an answer
A native sandbox denial of file-read-data on the agent's Agent
folder indicates a harness that opens the parent for reading before
accessing its conversations. Update the Link harness and restart the
agent. The harness traverses this parent without listing it; access to
each child stays subject to the sandbox's grants.
It doesn't answer on a connection
Run lnk agent logs --follow. The connection plugins' log is
~/.lnk/agents/<agent>/bridge.log.
Model setup
Model errors can come from a missing selection or the provider's credential. Inspect the returned error before changing the model's configuration.
"Your agent couldn't answer", and its log says "the model answered 401"
Start it again with the right key: ANTHROPIC_API_KEY=... lnk agent start (or your provider's variable).
"no model named for ..."
Name the model it runs on: lnk agent start --model <name>, a hosted
model's name or one lnk model list shows running on this computer.
"Signal isn't linked"
Run lnk agent connect signal in a terminal, and scan the code from
the agent's phone (Settings > Linked Devices > Link New Device).
It forgot something from long ago, or makes things up about it
Past the window it's sent, it has only its summary. A larger [window] max in its spec (lnk agent show --opinions) helps, at a higher price per
message, up to the model's own. lnk agent memory start lets it search
the conversation's files, which keep everything.
"the model refused the prompt as longer than its window"
The window you set is more than the model takes. Set a smaller
[window] max, or correct the model's window in
~/.lnk/model-facts.toml (lnk model show <model>).
"the model answered 400 ... does not support tools"
Pick a model that takes tools (lnk agent start --model qwen3), or
lnk agent memory stop.
A model on your computer is slow, ignores its notes, or cuts a long answer
On a model on your computer it's slow, ignores a note it was given ("I
don't have access to your personal preferences"), or can't write out a
long answer. A small model (qwen3:8b) takes tens of seconds a turn
with memory on, and tries a tool's call more than once. It may not use
a note in its prompt, and its runtime may run it with a window too
small for a long answer (ollama ps shows its context).
Use a larger model
Use a larger model, or a hosted one: lnk agent start --model claude-sonnet-5-5, which asks for the key unless ANTHROPIC_API_KEY
is set or one is kept. start and status mark such a model ⚠️.
A skill isn't in lnk agent show --instructions
Its SKILL.md must start with front matter between two lines of ---,
with a name the same as its folder's and a description. lnk agent skill add says what's wrong with one.
Tool failures
Tools can fail while starting or during a call. Inspect their logs to distinguish a missing tool from one that was offered and returned an error.
A tool is missing from its answers
lnk agent logs says why ("tool ... left out of this turn"). lnk agent show --permissions lists the tools it may call.
A tool runs but fails
lnk agent logs --follow includes failed tool calls as well as startup
messages. Each notice names the tool, chat and returned error, without
printing the call's arguments. An idle agent may show only its startup
lines. Reproduce the failure while following the log to capture its cause.