SynaraDesktop and updates
Resolve Synara launch, window, architecture, packaged update, and reinstall problems without deleting useful state.
Treat the desktop application, its local server, and the installed provider runtimes as separate layers. A window problem does not automatically mean your repositories, provider credentials, or Synara workspace data are damaged.
Synara will not launch
Work through these checks in order:
- Confirm the installer matches your operating system and CPU architecture.
- Fully quit any existing Synara process.
- Start Synara again from the normal application launcher.
- Restart the operating system if a previous process cannot be terminated cleanly.
- Re-download the current installer from the official download page.
- Reinstall over the current application without deleting workspace data.
On macOS, use the Arm64 build for Apple Silicon and the x64 build for Intel. On Linux, ensure the AppImage is executable:
chmod +x Synara*.AppImageReplacing the application bundle and deleting Synara’s local data are different operations. As a rule, reinstall the application first. Preserve repositories, uncommitted changes, task evidence, and any data directory before considering destructive cleanup.
The window is blank or unresponsive
A blank window can come from the renderer, the local server, graphics state, or a process left over from an earlier launch.
- Wait briefly for initial startup and provider-health probes.
- Fully quit Synara rather than only closing the window.
- Start it again with no other Synara instance running.
- Disconnect unusual display, proxy, or security software only when you can do so safely and reversibly.
- Record whether the window is blank immediately or only after opening a specific project or surface.
- Capture the operating system, Synara version, and exact time before restarting again.
When only one project or task triggers the problem, report that boundary. It is more useful than “the app is blank.”
The local server does not become ready
Synara’s desktop UI depends on its local application server. Repeated connection or startup errors can result from:
- Another Synara process using the local runtime state
- A partially terminated previous launch
- A blocked local process
- A damaged or incompatible application installation
- Security software preventing the packaged server from running
Fully quit every Synara process, then relaunch. Do not expose or forward Synara’s local server ports as a troubleshooting shortcut.
The packaged update failed
- Preserve important Git work.
- Close active provider turns and terminal processes when practical.
- Fully quit Synara.
- Start it again and retry the update once.
- If the updater still fails, download the newest installer from trysynara.com/install or GitHub Releases.
- Install the new application over the existing application.
- Launch Synara and verify the displayed version before resuming important work.
An update failure does not prove that local task data was deleted. Avoid combining an update recovery with manual data-directory cleanup.
Synara opens but providers changed after an update
The application update and provider CLI updates are independent. After updating Synara:
- Restart the app so provider discovery runs against the current environment.
- Check each enabled provider’s detected executable and authentication state.
- Remove stale custom binary paths.
- Update the provider runtime through its own supported method when Synara reports that it is outdated.
- Start a new provider session when protocol or capability negotiation changed.
Continue with Provider troubleshooting.
Source build and packaged build behave differently
A development checkout and a packaged release may use different executable paths, environment variables, data locations, update behavior, and build-time configuration.
When reporting a problem, state whether you are using:
- A packaged release
- A locally built desktop application
- A website development server only
- A specific branch or commit
Do not use a successful website build as evidence that the packaged desktop runtime works.
Safe reinstall checklist
- Important repository changes are committed, stashed, copied, or pushed
- The correct installer and architecture were selected
- Every Synara process was fully closed
- The application was replaced before any data was deleted
- The version was checked after launch
- Provider detection and authentication were rechecked
- A small test task was completed before resuming important work
Still failing
Continue with Diagnostics, then prepare a focused report using Report a problem.