# Troubleshooting

> **What you will learn**
> What to check, in what order, for each symptom — and what to bring when you
> ask for help.

## Three things first

Whatever the symptom, start here. More than half end at this step.

```
□ Is there credit left?        → usage screen
□ Is this the right workspace? → check the name at top left
□ Have you refreshed?          → it is often only the screen
```

**The second is more common than you'd think.** With several workspaces, your
material and tools live somewhere else.

## Conversations

### No answer / it stops partway

```
1. Refresh                → the screen connection dropped
2. Check credit           → exhausted credit prevents new requests starting
3. Ask again              → transient errors clear here
4. Does the task use tools? → go to "tools" below
```

**Step 1 works often.** Live delivery is designed to tolerate loss, and the
content is written to the server first. Even when the screen drops, **a refresh
picks up where it left off.**

### It answers, but the content is off

| Symptom | Check first |
|---|---|
| Doesn't know internal material | is the file in [Drive](/guide/cn-drive)? |
| Material is there but not found | is the file readable as text? (scanned-image PDFs are not) |
| Answers from outdated information | is the Drive copy an old version? |
| Forgets a rule set earlier | long conversation — wrap up and start a new one |
| Answers differently every time | the instruction has no done condition |

The last two are covered in [when context gets pushed
out](/guide/ai-context-overflow) and [the four elements of a good
instruction](/guide/ai-intent-context).

## Agents and tools

### It won't use a tool

```
1. Is that tool enabled?          → check the tool settings screen
2. Are too many tools enabled?    → several similar ones and it picks wrong
3. Does the description say when to use it? → a thin description won't get called
4. Name it in the instruction     → "use the search tool to confirm"
```

Step 1 lives in [turning tools on and off](/guide/cn-tool-settings).

**Step 3 is often the cause.** Tool descriptions are read by the model, not by
people. A description that says *what it does* but not **when to call it**
rarely gets called.

### An MCP server won't connect

```
□ Is the URL exact?              (including the trailing path)
□ Have the credentials expired?  (OAuth tokens do expire)
□ Is the server up right now?    (the provider's status page)
□ Is the tool list empty?        → connected, but with narrow permissions
```

**The last line confuses people.** A successful connection with no usable tools
usually means the token you issued was scoped too narrowly.

### It calls the tool but gets an empty result

Likely a permission problem. Some servers quietly return nothing when a
read-only account calls a write operation. Go back to the first question in
[tools are permissions](/guide/mcp-security) — how far does this server reach?

## Systems

### A system shows as offline

```
1. Is the machine on?
2. Is HyperTeams running?
3. Did the network change?
4. Was the token revoked?
```

If step 2 is the suspect, go to [HyperTeams
troubleshooting](/guide/ht-troubleshooting).

**Connection state is judged from a periodic signal.** So after a reboot the
machine shows offline briefly and then reattaches. Give it a few minutes.

### A task is stuck as unfinished

Long-running tasks are normal. But **if the machine shuts down or the program
restarts**, an in-flight task loses its owner. Those tasks are eventually closed
out automatically, but **their results are gone.** You have to run them again.

> **Tell long tasks to write intermediate output to files.** Then an
> interruption doesn't send you back to the start.

### Only the tunnel-related features fail

The tunnel is a separate add-on attached to a [system](/guide/cn-systems). When
it lapses, **only address management** is blocked — status checks and commands
keep working. If "some of it works," look here.

## Routes from outside in

### Sent via a channel, widget, or email and nothing happens

```
1. Which workspace is it connected to? → it may have arrived elsewhere
2. Is the connection active?
3. Is there credit left?               → exhausted credit stops external requests too
4. Is an agent assigned to handle it?
```

**Check 1 first.** [Channels](/guide/cn-channels) and the
[widget](/guide/cn-chat-widget) connect per workspace.

## Scheduling and the queue

### It didn't run at the scheduled time

```
□ Is the schedule active?
□ Is the timezone right?
□ Was the target system online at that moment?
□ Was there credit at that moment?
□ Is the previous run still going? → overlapping runs push each other back
```

**The last line is a frequent cause.** An hourly schedule with a 90-minute run
falls further behind every hour. Adjust the interval in [queue and
scheduling](/guide/cn-queue).

## Cost

### Usage suddenly jumped

Narrow it down in this order.

```
1. Look at the distribution on the usage screen  → not the total: who and what
2. Concentrated on one user?                     → check their recent conversations
3. Concentrated at one time of day?              → check scheduled runs
4. Concentrated on one agent?                    → likely repeated tool calls
```

**3 and 4 cause the big incidents** — a scheduled job failing and retrying in a
loop, or an agent calling the same tool over and over. The full reduction order
is in [usage and credits](/guide/cn-usage).

## Permissions

### A screen or button is missing

Almost always a role issue.

| What's missing | Role required |
|---|---|
| Member, tool, and system admin screens | admin or above |
| System registration and policy changes | **owner only** |
| Billing and workspace deletion | **owner only** |

See the table in [members and roles](/guide/cn-members).

## If it still doesn't work

Bring **these five things** and it gets resolved much faster.

```
□ Workspace name
□ Link to the conversation (thread)
□ When it happened (approximately is fine)
□ What you asked and what came back
□ Does it reproduce — same symptom on a retry?
```

**The last line matters most.** A one-off and a consistent failure have entirely
different causes.

---

## Check yourself

**1. Why does a refresh often fix an answer that stopped partway?**

<details>
<summary>Answer</summary>

**Because content is written to the server first and screen delivery is designed
to tolerate loss.** Even when the live connection drops, the content itself
survives, so a refresh picks it up.
</details>

**2. Why might an enabled tool still never be called?**

<details>
<summary>Answer</summary>

**Because the description doesn't say when to call it.** Descriptions are read
by the model, not by people; one that only says what the tool does rarely gets
invoked. Too many similar enabled tools can also confuse the choice.
</details>

**3. Why does an hourly schedule keep falling behind?**

<details>
<summary>Answer</summary>

**The previous run takes longer than the interval.** A 90-minute run on an
hourly schedule overlaps and pushes each subsequent run back. Lengthen the
interval or split the task.
</details>

---

That is Connect. To revisit the concepts, go to [what Connect
is](/guide/cn-what-is-it); if a term is unclear, see the
[glossary](/guide/glossary).