Fix common desktop app problems: an empty window, updates, connection and sign-in, cloud threads, previews, blocked commands and missing folders.

On this page

Find your symptom, or the exact message, below. Each section says why it happens and what to do, most specific first. For the CLI, see Troubleshooting; for Windows-only behaviour, Ysra Desktop on Windows.

The window stays empty, or the app doesn’t open#

What you see Why What to do
Starting… The app is opening Wait a few seconds
Still starting. If nothing opens, reload. with Reload Opening takes longer than a few seconds Reload
Ysra couldn’t start. Reload, or restart the app. and What happened is in … The window is still empty 10 seconds after the app started Reload, then restart the app
A dialog Ysra couldn’t start: Restart the app. and where the log is The app couldn’t start at all Restart the app; if it repeats, send the log to support

The log records only problems at start: an error before the app drew, a page that didn’t load, a part of the app that stopped. It is at:

System Log
macOS ~/Library/Logs/Ysra/main.log
Windows %APPDATA%\Ysra\logs\main.log
Linux ~/.config/Ysra/logs/main.log

Reload or restart first. If the window stays empty, send a report, or send the log to support with the version you installed. Show log file, in Settings → General beside Send a report… and in the Send a report window, shows the log in Finder or File Explorer.

The app doesn’t update#

The app never updates itself; it shows Version N is available · Download at the bottom of Settings. See Update and uninstall.

Symptom Why What to do
A newer version is out, but there is no Download The app hasn’t checked again yet, or the check didn’t get through Restart the app, or download from the install page
The old version still opens after installing (macOS) The old copy was running, or the new one isn’t in Applications Quit Ysra, drag the new one into Applications and choose Replace
“Windows protected your PC” The installer isn’t signed yet More info → Run anyway
This version of Ysra can’t undo yet; update the app. A feature needs a newer app Update, then try again

Send a report#

When something goes wrong, tell the Ysra team from the app:

From Choose
The menu bar Help → Send a report…
Search (Cmd+K) Send a report
Settings Settings → General → Send a report…

The Send a report window says: “Say what happened and what you were doing. The end of this app’s log goes with it, with file paths, email addresses and keys taken out. Nothing you asked, read or wrote in a thread is included.” Type in What happened and choose Send report; the app confirms “Report sent. Thank you.”

The window also says where the log is, so you can attach it to an email to support@ysra.ai yourself. If the report can’t be sent from the app, it says so and where the log is.

This is separate from the error reports the app sends by itself when it crashes; see Error reports.

The app can’t reach Ysra#

The app says Why What to do
Can’t reach … Is Ysra running there? No connection to Ysra Check your internet connection, then Settings → Accounts → Check connection
No answer from … (timed out). Usually the network Try again; check any VPN or proxy
Ysra isn’t answering right now (502). It may be restarting; try again in a moment. Ysra is restarting Wait a minute and retry
Ysra is handling too many requests. Wait a moment and try again. Too many requests at once Wait and retry

Threads on this computer that were working pause, and continue when the connection is back. If the folder chip reads Folder not connected · retry, click it; see Lose the connection.

Sign-in#

The app says Why What to do
Your sign-in ended. Sign in again. A sign-in ends after 30 days without use, after Sign out or Sign out everywhere, or when the password changes Settings → Accounts → Sign in
The browser didn’t finish signing in. If the page didn’t open or didn’t load, use a password instead. The browser step didn’t complete in time Start again and choose Allow in the browser, or Use a password instead
Signing in was declined in the browser. Someone chose Don’t allow Start again if that was a mistake
Signing in was cancelled. / Signing in didn’t work. The browser step was stopped or failed Start again
That sign-in wasn’t accepted. Wrong email or password, or an expired CLI login Check the email and password
No saved ysra CLI login was found on this computer. Use the ysra CLI login needs a CLI sign-in here Sign in with the browser or a password, or run ysra login first
There’s no workspace on this account yet. Create one in the Ysra web app first. New account without a workspace Create a workspace in the web app, then reopen the folder
The server changed in Settings, so you’re signed out. Sign in again. Settings → Advanced → Server was changed Sign in again, or set the server back to Production

See Sign in and where you’re signed in.

A cloud thread won’t start#

Threads in Ysra’s cloud start from the same message box: pick a repository or New cloud project under Ysra cloud in Where. See Code in Ysra’s cloud.

What you see Why What to do
No Ysra cloud group in Where Cloud isn’t on for this account, or there is no plan Pick a plan in Settings → Billing, or work on a folder on this computer
Connect GitHub… instead of repositories GitHub isn’t connected Connect it in the web app (Workspace → Integrations); its repositories then show here
A notice: “This runs in Ysra’s cloud: your project’s code is copied to a private, temporary sandbox …” Shown once, before your first cloud thread Continue to start, or Cancel
“Ysra’s cloud comes with a plan. Pick one in Billing, or run this on your own computer.” No plan See plans
“Your plan runs N cloud tasks at a time. This one starts when one finishes, or run it on your own computer.” The plan’s limit on tasks at once Wait, or stop another cloud thread
“That’s a lot of cloud tasks in an hour. Try again in a few minutes, or run it on your own computer.” The plan’s machine starts per hour Try again later
“This month’s N cloud hours are used. They come back on the 1st; your own computer still works.” The plan’s cloud hours Work on this computer until the 1st
“Ysra’s cloud is busy right now. Your task starts as soon as a machine frees up.” Every machine is in use for now Wait: it starts by itself
“Cloud work is switched off for this account. Write to support@ysra.ai.” Switched off by Ysra Write to support
“Mayz reviews a folder on this computer or a repository in Ysra’s cloud. Choose one of those.” A Mayz review was asked on a device or a new cloud project Pick a folder here or a repository

The plan limits are in Limits and costs. A cloud thread has no Undo changes… or Commit…: its changes are on its own branch, delivered with Open pull request….

A preview won’t open#

The Preview button at the top of a thread opens the app being built in a small browser beside it.

What you see Why What to do
Nothing is running yet. Start the app and it shows here. A thread on this computer; the app isn’t running Start preview, or ask Ysra to start the dev server
This needs its app running in the cloud. A cloud thread whose app needs its server Start preview; it waits about 3 minutes for the app
“The preview didn’t start in 3 minutes.” / “The app stopped. Here are its last lines.” The app didn’t start, or crashed Read the lines shown, then ask Ysra to fix it
Changes show after a reload. A cloud preview shows the app as it was Reload in the preview’s bar
Expo Go won’t open a phone app The phone’s Expo SDK differs from the app’s See Phone apps and the Expo SDK

Every preview state and message: Previews.

An older thread can’t continue#

Some threads from earlier versions of Ysra can’t be continued. Such a thread says so when you open it. Start a new thread on the folder, or a new cloud thread on the repository; see Start a thread.

A folder isn’t shown, or Ysra can’t see it#

The app says Why What to do
Folder not connected · retry The connection to the folder dropped Click the chip at the top of the thread to reconnect
… isn’t on this computer anymore. The folder was moved or deleted Open it again from its new place
This folder’s location on this computer isn’t known. Open it in Ysra here. The thread was started on another computer Open the folder here with New thread
Your whole home folder can’t be opened. Pick the project folder inside it. Home folders, whole disks (A whole disk can’t be opened.) and system folders (That’s a system folder. Pick a project folder.) are refused Pick the project folder itself

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.

On macOS and Linux Ysra only runs commands where they can be contained to your folder.

System What to do
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
Windows You won’t see this message: each command asks first instead, unless you choose WSL. See Ysra Desktop on Windows

Settings → General → Your tools says whether Ysra can run commands here.

The thread says Why What to do
You didn’t approve that, so I didn’t run it A question went unanswered or was declined Ask again and answer the card
On Windows I don’t run commands that delete or overwrite, yet: do it yourself if you want it. Windows with each command asking Do it yourself, or choose WSL. See Windows

Docker is blocked#

What you see Why What to do
A Use Docker? card A command needs Docker, once per thread 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.

Low credits or none left#

What you see Why What to do
92% of this month’s credits used. 480 left; plan credits refill on 7 Nov. with Add credits 10% or less of this month’s credits left Nothing yet; work carries on
The credits ran out. Work that uses credits is paused until more are added. (Home, Usage) No credits left Add credits, or wait for the monthly refill
I paused because the credits ran out. Your changes are saved. Tell me to continue once there are credits. (in a thread) The running task paused before its next paid step Add credits, then tell Ysra to continue
I paused because this account is paused. Your changes are saved. Write to support@ysra.ai. The account is paused Write to support

See When credits run out.

A device or machine#

The app says Why What to do
edge-01 is offline. Run ysra serve there. The device isn’t running ysra serve Start ysra serve on the device
edge-01 isn’t sharing a folder. Run ysra serve --folder … there. Nothing is shared from it Share a folder from it
edge-01 is in observe mode, so I only look there. Switching it to change mode is your call (ysra machines mode edge-01 change). New devices and machines start read-only Switch it to Change in Settings if you want Ysra to edit there
That question has expired. A machine card went unanswered for 15 minutes Ask again
That’s a secret file (keys, passwords, credentials); I don’t read those on machines. Deliberate Read it yourself if you need it
I couldn’t get a host key from web-01:22. Is it reachable from this computer? SSH to the host doesn’t work on its own Check the SSH host alias works with plain ssh first

Where the record of Ysra’s work is#

Everything is in ~/.ysra, readable only by you:

What Where
Every file operation Ysra made in a thread: time, operation, path, result. Never file contents or command output ~/.ysra, one file per thread
What ran on each machine and who approved it ~/.ysra/targets/<name>/log.jsonl, also under Settings → Machines → Log
Tools Ysra installed ~/.ysra/tools
Parallel copies ~/.ysra/worktrees

Problems when the app starts are in its own log, main.log; see above.

When you contact support, include the version line from the bottom of Settings (you can select and copy it) and what the thread said.

YsraDocs