After the session
When something fails
Something is going to fail at some point, and that's normal. This lesson gathers the most common problems and how to get out of each one.
The installation
| Symptom | What to do |
|---|---|
command not found or "is not recognized as a command" | Close the terminal and open a new one. If it keeps happening, reinstall with another option from the installation lesson. |
npm: command not found | You're missing Node.js. Install it from nodejs.org (LTS version) and open a new terminal. |
| The interface looks weird or has strange symbols | Use a modern terminal. On Windows, the Terminal app works better than the old console. |
The connection to the model
| Symptom | What to do |
|---|---|
| Authentication error or "invalid key" | The key was pasted wrong. Run /connect again and paste the whole key, with no spaces. |
| "Rate limit" or the model doesn't answer | The free model is overloaded or you hit the daily cap. Switch models with /models, or wait until the next day. |
| It answers, but very slowly | This happens with free models at busy hours. Try another free model. |
The agent
| Symptom | What to do |
|---|---|
| It says it can't see your files | You opened it in another folder. /exit, go into the right folder, and open opencode again. |
| It doesn't ask your permission before changing files | opencode.json is missing from the folder, or it has a formatting error. Check that it's identical to the one from the workshop. |
| It did something different from what you asked | Reject it and ask again with more detail. Also say what it must not touch. |
| The conversation got very long and it's getting confused | Start a new one with /new. |
How to ask for help well
If you're going to ask in the community, include three things:
- What you wanted to do (one sentence).
- What command you typed or what you asked the agent, copied exactly.
- What came out, copied exactly, or a screenshot. Cover your key if it shows up.
With those three things, almost any problem gets solved in one message.
Summary
- Most installation failures are fixed with a new terminal.
- Most connection failures are a key pasted wrong or an overloaded free model.
- To ask for help: what you wanted, what you typed, what came out. And never your key.