Troubleshooting

Nearly every report falls into a handful of 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, the MCP server refuses to start, a gRPC call fails over TLS, or sync will not turn on. 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/client

Windows, PowerShell:

& "$env:LOCALAPPDATA\Programs\Tetiva\client.exe"

That is %LOCALAPPDATA%\Programs\Tetiva\client.exe. A copy installed by version 1.2.0 or earlier sits in C:\Program Files\Saveliy Yudin\Tetiva\client.exe instead.

Linux:

tetiva

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 and Linux, %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_DIR before 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.

A different story: the server runs, but the agent gets a 401. That means the config was written before the access token existed. Press Copy config in settings, pick your client, and replace the old entry with what it copied. Details on the MCP server page.

gRPC: a TLS error or "too many colons in address"#

If the server uses TLS and the address has no scheme, or the other way round, the error says which way to go: The server may require TLS — use grpcs:// or The server may not use TLS — remove grpcs://. Fix the address or click the lock before it. too many colons in address on another device means it runs Tetiva 1.2.1 or older, which can't read an address with a scheme: update it. Details on the gRPC page.

Sync will not turn on#

An amber cloud icon with a dot means the email is not confirmed. For a cloud account, confirming and resending both live on the site: follow the link from the message, or ask for a new one from your account page. The Send again button in the app only exists on the Check your email screen, which cloud users rarely see. A red icon reading Session expired — sign in to resume sync means the session ended and you need to sign in again. Every state is listed on the Sync page.

It asks you to sign in again after an update#

On the first launch after upgrading from 0.17.0 or earlier, the app shows a Sign-in has changed with this update. Please sign in again. notification with a Sign in button. Nothing is broken: the sign-in scheme changed and the old session no longer fits. Sign in once and sync starts again.

Upgrade every machine at the same time: an older version will not accept an auth scheme it does not know, and sync on the machine left behind stops at Sync stopped — update the app to read the newest changes.

The browser does not open for sign-in#

Browser sign-in and the Authorization Code grant open the browser for you. If it did not open, the waiting panel offers Open again and Copy link so you can open the URL by hand; the OAuth 2.0 form has the same two buttons. Device Code opens nothing by itself: it shows the verification address, the user code with a copy button next to it, and a single Open.

The Authorization Code grant has one more failure mode: it needs a free port on 127.0.0.1, and a busy one is reported as an error right under the Redirect Port field. Put 0 there and a free port is picked for you. Details on Sync and Authentication.

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.