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.

text

□ 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

text

1. Refresh                → the screen connection dropped2. Check credit           → exhausted credit prevents new requests starting3. Ask again              → transient errors clear here4. 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?
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 and the four elements of a good instruction.

Agents and tools

It won't use a tool

text

1. Is that tool enabled?          → check the tool settings screen2. Are too many tools enabled?    → several similar ones and it picks wrong3. Does the description say when to use it? → a thin description won't get called4. Name it in the instruction     → "use the search tool to confirm"

Step 1 lives in turning tools on and off.

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

text

□ 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 — how far does this server reach?

Systems

A system shows as offline

text

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.

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. 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

text

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

Check 1 first. Channels and the widget connect per workspace.

Scheduling and the queue

It didn't run at the scheduled time

text

□ 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.

Cost

Usage suddenly jumped

Narrow it down in this order.

text

1. Look at the distribution on the usage screen  → not the total: who and what2. Concentrated on one user?                     → check their recent conversations3. Concentrated at one time of day?              → check scheduled runs4. 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.

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.

If it still doesn't work

Bring these five things and it gets resolved much faster.

text

□ 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?

Answer

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.

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

Answer

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.

3. Why does an hourly schedule keep falling behind?

Answer

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.

That is Connect. To revisit the concepts, go to what Connect is; if a term is unclear, see the glossary.