Troubleshooting

A chapter to look things up in. Find your symptom.

First — how to read the log

Most problems have their answer in the log.

bash

cat logs/server.log

Just the end:

bash

tail -50 logs/server.log

If it died on the previous run:

bash

cat logs/server.log.prev

Install and startup

`hyperteams: command not found`

The most common problem.

Open a new terminal window. The install changes your path settings and an already-open terminal does not know.
If that fails, restart the computer
If that fails, the install did not complete → install again

It starts and immediately stops

Check the log. Usually a prerequisite problem.

bash

claude --version   # does it print?node --version     # does it print?

If either does not, fix prerequisites first.

The port is already in use

bash

PORT=9000 hyperteams

To change the default, hyperteams setup.

The address prints but the browser will not open it

Did you type it exactly, including http://
Is a firewall blocking it
Try another port → PORT=9000 hyperteams

Access and authentication

I do not remember the password

bash

hyperteams setup

I connected the tunnel but it will not open from outside

Did you restart? hyperteams restart is required after connecting a tunnel
Did you use the exact address
Does the dashboard settings screen show the tunnel as connected

Running tasks

I handed over a task and nothing happens

text

□ Is the Claude Code login still valid?  → run claude in a terminal□ Is the working directory path valid?    → does the folder actually exist□ Are there errors in the log?            → tail -50 logs/server.log

The first is the most common. When the Claude Code login expires, HyperTeams stops with it.

It touches the wrong files

Your working directory is probably drawn too wide. Redraw it narrowly.

And state the scope in your instruction — writing it as what not to do is effective.

I keep disliking the results

The cause differs by symptom.

Symptom	Cause	Response
Only generic answers	missing context	add the situation to the folder description and the instruction
It forgets earlier instructions	context pushed out	split into a new task
It does what you said not to	scope unspecified	state what not to do
Unclear whether it finished	no done condition	add a pass criterion

The job runs far too long

The task is too big. Split it smaller — one task fitting in a single sentence is about the right size.

Performance and resources

The machine gets slow

text

□ have you left several terminals open and forgotten them□ are too many tasks running at once

Clean up terminals you are not using.

Costs are higher than expected

text

□ how many scheduled runs are going□ are there schedules left over whose purpose is gone□ are you using a heavy model for simple work

See the cost section of the scheduled runs chapter.

Data and recovery

My records disappeared

hyperteams upgrade does not touch data. If you reinstalled, data may have been removed.

The work went wrong and I want to undo it

If you use git, undoing there is the most reliable route. That is why committing before starting is recommended.

Without git you depend on your editor's undo or a backup.

If none of that works

Get in touch, with the log.

bash

tail -100 logs/server.log

Contact: [email protected]

Walk the recovery order once, for yourself. Thirty minutes → Recover a stalled job

Including these speeds things up:

text

□ OS and version□ hyperteams --version□ claude --version / node --version□ what you were trying to do and what did not work□ the end of the log