Nearly every report falls into five stories: the operating system objects to the installer, the app cannot find your old data, you need logs, you need to move or wipe the database, or the MCP server refuses to start. Here is what to do in each case, and what to attach if the problem survives.
Windows: the SmartScreen warning#
The Windows installer is not signed yet. SmartScreen shows its blue "Windows protected your PC" dialog: click More info, then Run anyway. The installer pulls in WebView2 by itself if the system lacks it. Only take the file from the links on this site; Installation says where they are.
macOS: Gatekeeper and quarantine#
The macOS build is signed with a Developer ID and notarized by Apple, so the normal path is: open the DMG, drag Tetiva into Applications, launch it, no warnings anywhere.
If macOS still claims the app is damaged or cannot be verified, the file is almost always the culprit rather than the signature: a truncated DMG, a third-party unarchiver, a corporate proxy rewriting the payload. Download it again. Stripping the quarantine attribute by hand (xattr -d com.apple.quarantine /Applications/Tetiva.app) is only reasonable when you trust the source — it switches the check off, it does not repair it.
Getting the logs#
Tetiva writes JSON logs to standard output and keeps no log file, which means running it from a terminal and reading the output there.
macOS:
/Applications/Tetiva.app/Contents/MacOS/clientWindows, PowerShell:
& "C:\Program Files\Saveliy Ludin\Tetiva\client.exe"Reproduce the problem with the terminal open and save what it printed — that output is the single most useful thing you can send.
The app cannot find your old data#
On the first launch after the rename, ~/.gophercourier is renamed to ~/.tetiva. One case skips it: ~/.tetiva already exists. The app then works with the new, empty directory while the old one sits untouched beside it. Quit Tetiva, rename the empty ~/.tetiva, put the old directory in its place, and start the app again.
Moving and resetting data#
Everything local lives in one directory — ~/.tetiva on macOS, %USERPROFILE%\.tetiva on Windows — holding data.db and its WAL sidecar files.
- Move to another machine. Quit the app first, otherwise the WAL has not been folded back into the database, then copy the whole directory.
- Reset to a clean state. Quit the app and delete the directory. Local collections, history and cookies are gone for good; workspaces that lived in Tetiva Cloud come back after the next sign-in.
- Keep the database elsewhere. Set
TETIVA_DATA_DIRbefore launch. Note that an app started from Finder or the Start menu never sees variables from your shell profile — launch it from a terminal with the commands above.
Theme, font size and line wrapping are not stored in that directory and will not travel with it; you will set them again, see Settings.
The MCP server will not start#
If Enable is on but the status stays ○ Stopped, the port is usually taken — by another program or by a second Tetiva instance. The log carries an MCP port unavailable line at startup; the app keeps running and only MCP is off. Change the port in settings and restart. Details on the MCP server page.
Sync will not turn on#
An amber cloud icon with a dot means the email is not confirmed: follow the link from the message, or resend it from the Sync window. A red icon reading "Session expired" means the session ended and you need to sign in again. Every state is listed on the Sync page.
Where to report a problem#
Bugs and feature requests go to the issues of github.com/tetiva-app/client. Short questions and general feedback are welcome on Telegram.
Include the version from the About section in settings, your operating system, the steps to reproduce, and the terminal output. Give that output a quick read before sending — tokens and internal hostnames have a habit of ending up in logs.