Troubleshooting
What to do when the desktop app can't reach Ysra, sign-in fails, a folder isn't shown, commands or Docker are blocked, or a first task is slow — and where to find the record of what was done.
On this page
I can't reach Ysra#
| The app says | What to do |
|---|---|
| Can't reach … Is the engine running? | Check your internet connection, then Settings → Engines & accounts → Check connection |
| No answer from … (timed out). | Usually the network. Try again; check any VPN or proxy |
| The engine isn't answering right now (502). It may be restarting; try again in a moment. | Wait a minute and retry |
| The engine is handling too many requests. Wait a moment and try again. | Wait and retry |
Threads that were working pause, and continue when the connection is back.
Sign-in#
| The app says | What to do |
|---|---|
| Your session on this engine expired. Sign in again. | Settings → Engines & accounts → Sign in |
| This engine did not accept the login. | Check the email and password |
No saved ysra CLI login was found on this machine. |
Sign in with your email and password, or run ysra login first |
| There's no workspace on this account yet. Create one in the Ysra web app first. | Create a workspace in the web app, then reopen the folder |
A folder isn't shown, or I can't see it#
| The app says | What to do |
|---|---|
| I can't see this folder · retry | Click the chip to reconnect |
| I can't find … on this computer anymore. | The folder was moved or deleted. Open it again from its new place |
| I don't know where this folder is on this computer. Open it in Ysra here. | The thread was started on another computer. Open the folder here with New thread |
| I won't work on your whole home folder. Pick the project folder inside it. | Pick the project folder itself. The same goes for a whole disk or a system folder |
A thread only lists under its folder once the folder has been opened and trusted on this computer.
Commands are blocked#
I can't run commands on this computer yet: it has no safe way to contain them.
I only run commands where they can be contained to your folder.
- Windows: running commands isn't available yet. I read and edit files.
- Linux: install what's missing:
sudo apt install bubblewrap socat ripgrep. - macOS: this shouldn't appear. Update the app, and contact support if it persists.
Settings → General → Your tools says whether I can run commands here.
You didn't approve that, so I didn't run it means a question went unanswered or was declined. Ask again and answer the card.
Docker is blocked#
| What you see | What to do |
|---|---|
| A Use Docker? card | Choose Allow for this session |
| Docker is off for this session. I'll ask again if a command needs it. | You revoked it, or said not now. Say "continue" and allow it |
| A Start Docker? card | Docker isn't running. Choose Go ahead, or start it yourself |
The first task on a folder is slow#
The first task reads more: your project's layout, how it installs and how its checks run. Installing dependencies and the first full run of your checks take as long as they do for you. Later tasks on the same folder start faster.
If a thread shows Live connection unavailable, updating every few seconds, it is still working; updates just arrive in steps.
My balance is low#
A Your balance is low card pauses the task. Add credit in your Ysra account, then choose I've added credit, continue.
A device or target#
| The app says | What to do |
|---|---|
edge-01 is offline. Run ysra serve there. |
Start ysra serve on the device |
| edge-01 is in observe mode, so I only look there. | Switch it to Change in Settings if you want me to edit there |
| That question has expired. | A target card went unanswered for 15 minutes. Ask again |
| That's a secret file (keys, passwords, credentials); I don't read those on targets. | This is deliberate; read it yourself if you need it |
| It didn't answer with a host key. | Check the SSH host alias works with plain ssh first |
Where the record of my work is#
Everything is in ~/.ysra, readable only by you:
| What | Where |
|---|---|
| Every file operation I made in a thread: time, operation, path, result. Never file contents or command output | ~/.ysra, one file per thread |
| What ran on each target and who approved it | ~/.ysra/targets/<name>/log.jsonl, also under Settings → Targets → Log |
| Tools I installed | ~/.ysra/tools |
| Parallel copies | ~/.ysra/worktrees |
When you contact support, include the version line from the bottom of Settings (you can select and copy it) and what the thread said.