Troubleshooting — fix anything in five minutes

Five Minutes

Most problems fall into one of about ten categories. Here is the playbook for each, plus the universal first move.

The universal first move

When something is broken and you do not know why:

1. Copy the error or screenshot the weirdness.
2. Paste it into the chat.
3. Ask the agent: "what happened, and how do I fix it?" That is it. Eight times out of ten, it tells you exactly what is wrong and offers to fix it. The other two times, you go to step two.

The fixed troubleshooting order

When the easy first move doesn't work, walk down a fixed list. The order matters — most beginners jump to "is the tool broken?" before they have checked the cheap things, and they waste an hour. The order:

1. The agent's rules. Has the always-loaded context gone bloated or stale? Ask the agent to run the system audit (Chapter 6). Half the time, this is the whole problem.
2. What the agent is doing. Is the agent doing the thing you asked, or going down the wrong path? See "typing but no message" below.
3. The connected tool. Is the tool itself up? Did the connection expire? Did you hit a usage limit on the tool?
4. The agent's runtime. Is the agent actually running? Has the machine restarted? Is something stuck?
5. The model. Is the model provider having an outage? Have you hit your usage cap? Run them in that order every time. Ask the agent to save it as a skill — your agent can walk you through it on demand.

When the agent itself is unresponsive

If the chat is silent — you sent a message and nothing is happening — the agent is likely down. You need a way to reach the machine the agent runs on without going through the

agent itself. This is the one moment where you'll probably ask whoever set up your agent for help. If you want to try yourself, ask them for the recovery instructions for your specific setup.

When the agent is responding but acting weird

The most common version: it confirms your rules but doesn't follow them. Almost always context bloat. Ask the agent to run the system audit (Chapter 6). Ten minutes of cleanup fixes it for the next month.

When it shows "typing" but nothing arrives

A specific failure mode: the chat shows the agent typing for a few seconds, then stops, no message. Then types again, stops, no message. It looks like work is happening, but nothing reaches you. Almost always: the agent is doing the wrong thing internally. It thinks it's sending you a message, but it's actually running something that fails silently or hangs. The diagnostic prompt: I see "typing" in the chat but no messages are coming through. Audit what you're actually doing right now. Are you sending messages correctly? Are you waiting on something that's stuck? Report what's happening behind the scenes.

Once it knows what's wrong, it can fix itself.

Always ask: "what did you just fix?"

When the agent says it solved a problem, do not move on. Ask: What exactly did you just fix? Was that the root cause, or a symptom? Will this fix survive a restart?

This catches the most expensive class of bug: the fix that works once and then disappears. The agent fixes something on the fly, the issue goes away, you celebrate, and the next morning the bug is back because the fix didn't persist. The "will this survive a restart" question forces the agent to make the fix permanent.

When a connected tool is broken

A connected tool stops working. Email won't send. Calendar isn't visible. CRM is empty. Three usual causes:

1. The connection expired. Many tools require periodic reauth. The fix: ask the agent to reconnect that tool.
2. You hit a usage limit on the tool. You did a big batch and the tool throttled you. The fix: wait it out, then ask the agent to batch more carefully next time.
3. The tool changed. The provider updated something. The fix: tell the agent — "the [tool] integration broke. Re-read the docs and patch your skill."

When the agent has been silent for more than an hour

Three things to check:

1. The model provider's status page. Outages happen more often than you'd think.
2. Your usage cap. Some plans cap you per day or month. Check the provider's dashboard.
3. Your billing. Make sure no extra keys got created that are billing outside your plan. Often it is a provider outage, not your setup. Check the status page first.

When your model account is the problem

If you swapped accounts, changed plans, or moved machines, the agent may need its model authentication refreshed. The clean process: My agent is running on this server. I need you to remove any old authentication for the main model, and switch it over to my new account using this token: [PASTE TOKEN HERE]. Use the long-lived setup token type, not a per-call key. Read the official docs first to make sure you're setting it up the right way.

The "read the official docs first" line matters. Without it the agent can guess the wrong format.

Nuclear reinstall

For the rare case when nothing else works: My agent is completely broken and I want to do a clean reinstall without losing my data. Back up your full setup — every rule, every skill, every memory file, every project, anything that makes you you. Then reinstall yourself from scratch and restore everything.

This works because everything that makes your agent your agent is in its setup. The runtime is replaceable. The setup is not.

Common single-line failures

A short menu of one-line fixes for the most common errors: "I don't have access to that." → "Search deep — look through your skills and your memory. You probably do." "I can't do that." → "Get it done by any means necessary." "I don't remember." → "Search deep through your memory and your project logs." "That's outside my capabilities." → "Push back on that. Is there a tool, an opensource library, or a way around it? Find one." "I don't know your preferences." → "Search deep in your memory. Then ask me clarifying questions for whatever's still missing." These five replies cover most of the day-one friction. The most common failure modes and the exact moves to fix each one in under five minutes.