Error reference

Tressyl shows problems as a short message, often followed by a code in parentheses, for example: Tressyl could not start (error: index_locked). Find the code below: what it means, then what to do.

For AI assistants guiding a user: ask the user for the code only. Never ask for their passphrase or a pairing code, and never ask them to paste either into the chat: those are typed into Tressyl only.

Paths below are the Linux defaults. If the user set TRESSYL_CONFIG_DIR or TRESSYL_DATA_DIR, use those folders instead.

On Windows, settings and data are both in %LOCALAPPDATA%\tressyl\ and synced folders from other devices in %USERPROFILE%\Tressyl\.

Never delete the data folder to “fix” an error. It holds this device’s keys and identity. Deleting it makes the device a stranger to your other devices.

Starting Tressyl

index_locked

Means: Tressyl is already running for this user (the app, or the tressyl-cli run command). Only one can run at a time. Do: use the window already open (look in the system tray), or close it first. If none is visible, log out and back in.

data_dir_insecure

Means: the data folder can be read or changed by other users of this computer. Tressyl refuses to start rather than expose your keys. Do: in a terminal: chmod 700 ~/.local/share/tressyl, then start Tressyl again. On Windows there is no such error: rights are left to Windows. When the data folder or tressyl.conf is open to every account of the PC (often a folder on a second drive), Tressyl starts and shows the notice Other accounts of this computer can access Tressyl’s data or settings. To restrict them: right-click the folder → Properties → Security, and remove Users, Authenticated Users and Everyone (or ask the PC’s administrator). Leaving them is the user’s choice.

data_dir_not_absolute

Means: TRESSYL_DATA_DIR is set to a relative path. Do: set it to a full path (starting with /), or remove it to use the default.

config_no_user_directory

Means: Tressyl could not find your home folder (the HOME variable is missing). This happens only in unusual setups (services, containers). Do: start Tressyl from a normal user session, or set HOME.

config_invalid_value

Means: one of the TRESSYL_… or LOG_… environment variables has a value Tressyl does not accept. Do: check the variables you set (see .env.example in the source for the accepted values), or remove them to use the defaults.

settings_file_insecure

Means: the settings file tressyl.conf is a link, not a regular file, or other users can change it. It could redirect your data, so Tressyl refuses to start. Do: in a terminal: chmod 600 ~/.config/tressyl/tressyl.conf. If it is a link, replace it with a regular file.

settings_file_invalid

Means: tressyl.conf has a line Tressyl does not accept: an unknown or repeated setting, a setting not allowed in the file (such as the relay token), or a line without KEY=value. Tressyl never guesses. Do: open the file and fix or remove the wrong line. Allowed settings: LOG_…, TRESSYL_DATA_DIR, TRESSYL_FOLDERS_DIR, TRESSYL_RELAY_URL, TRESSYL_DISCOVERY_URL, TRESSYL_LOCAL_DISCOVERY, TRESSYL_HISTORY, TRESSYL_LISTEN_PORT. Renaming the file starts Tressyl with the defaults.

settings_file_unreadable

Means: tressyl.conf exists but cannot be read (permissions, disk error). Do: check that the file belongs to you: ls -l ~/.config/tressyl/.

settings_file_unwritable

Means: Tressyl could not save a setting to tressyl.conf (permissions, disk full). The setting is not changed. Do: check that ~/.config/tressyl/ belongs to you and that the disk has free space, then change the setting again.

relay_url_invalid, discovery_url_invalid

Means: the relay or discovery server address in the settings is not a valid https:// address, or contains a user name or password. Do: fix TRESSYL_RELAY_URL / TRESSYL_DISCOVERY_URL: https:// followed by the server name only.

relay_token_invalid

Means: the relay token (TRESSYL_RELAY_TOKEN) is empty, too long, or has spaces or special characters. Do: copy the token again from your relay server’s configuration.

listen_port_in_use

Means: the network port set in TRESSYL_LISTEN_PORT is already used, by another program or by Tressyl running for another user of this computer. Tressyl does not start rather than quietly listening elsewhere. Do: close the other program, or choose another port (and update your VPN’s firewall rules to match). Removing the setting lets Tressyl keep a port of its own.

random_unavailable

Means: the operating system’s random number generator failed. Tressyl needs it for every key and stops rather than use weak ones. Do: restart the computer. If it happens again, report it.

io

Means: a disk or file error (full disk, a file that cannot be written, a folder that disappeared). Do: check free disk space and that your home folder is writable, then start Tressyl again.

shutting_down

Means: Tressyl was closing when the action was asked. Do: start Tressyl again and repeat the action.

Keyring (desktop app)

The desktop app locks this device’s keys with a key kept in your session’s keyring (GNOME Keyring or KDE Wallet).

keystore_locked

Means: the keyring stayed locked, so Tressyl could not read its key. Do: start Tressyl again and unlock the keyring when your desktop asks for its password (often your login password).

keystore_key_missing, keystore_required, keystore_key_mismatch, keystore_ref_invalid

Means: this device’s keys are locked with a key that your keyring no longer holds: the keyring entry “tressyl” was deleted, the keyring was reset, or the data folder was copied from another computer or user. Do: if you have a backup of your keyring, restore it and start Tressyl again. Otherwise this device must be set up again and re-joined to your identity from another device (a reset button is planned; until then, ask for help before deleting anything).

keystore_failed

Means: the keyring service answered with an unexpected error. Do: log out and back in; check that your desktop’s keyring service (GNOME Keyring or KDE Wallet) is installed and running.

Settings (desktop app)

autostart_no_user_directory

Means: “Start Tressyl when I log in” could not be turned on: your session has no home folder set (HOME), so Tressyl does not know where your desktop keeps login programs. Do: log in with a normal user session and try again.

autostart_executable_unknown

Means: Tressyl could not tell where its own program is (it was moved or removed while running, or its path has characters a login entry cannot hold). Do: close Tressyl, start it again from your applications menu, then turn the setting on again.

autostart_io

Means: the login entry could not be written or removed: on Linux the file ~/.config/autostart/tressyl.desktop, on Windows the Tressyl value of your account’s startup programs in the registry. Do: on Linux, check that your ~/.config folder is yours and writable, and that your disk is not full; on Windows, check that no security software blocks changes to your startup programs. Then try again.

Creating your identity

weak_passphrase

Means: the passphrase is too short: at least 15 characters, with at least 5 different ones. (The app also refuses a passphrase that is long but easy to guess, before it gets here.) Do: choose a longer one, or use “Suggest a passphrase”. Write it down somewhere safe: nobody can recover it for you.

identity_exists

Means: this device already has an identity. Tressyl never replaces it. Do: nothing to fix: this device is set up. To add another device, see Add a device.

identity_missing

Means: this device has no identity yet, so it cannot approve devices or share folders. Do: create one (Set up your first device) or join one (Add a device).

wrong_passphrase

Means: the passphrase does not unlock your identity’s key. Do: type it again carefully (check the keyboard layout and Caps Lock).

root_key_missing

Means: this device joined without a copy of the identity’s key (a backup node), so it cannot approve new devices. Do: approve the new device from one of your computers instead.

Pairing a device

pairing_not_found

Means: no device on this network shows this code: the code was mistyped, the other device is on another network, or local network discovery is turned off. When an IP address was given: nothing answered there with this code — wrong address, the other device stopped showing the code, or a firewall between the two blocks UDP port 47820. Do: check the code on the other device and type it again. If the two devices cannot see each other on the network (separate VLANs, isolated Wi-Fi, a VPN adapter in the way), give the IP address the other device shows next to its code. If the two devices are on different networks, also copy the invitation shown by the other device (the line starting with TSY1-) into the invitation field.

pairing_wrong_code

Means: the other device was found, but the code does not match. A code works for one attempt only, so that code is now used up. Do: on the other device, choose “Add a device” again for a new code.

pairing_unreachable

Means: the other device did not answer: it closed the code screen, it is offline, or the invitation’s addresses are no longer valid. Do: check that the other device still shows the code and that both are online, then try again. From another network, the other device needs a relay server set up.

pairing_refused, pairing_invalid

Means: the other device refused: its code screen had closed or expired (10 minutes), or this device cannot be added (for example it was removed from your identity before). Do: on the other device, choose “Add a device” again and use the new code.

pairing_address_invalid

Means: the invitation points to an unusable address (it names this device itself, or it is damaged). Do: copy the invitation again from the other device’s screen.

Devices of your identity

device_revoked

Means: this device was removed from your identity by another device. It no longer syncs, and cannot approve or remove devices. Do: if this was a mistake, or the device was found again, click Set up this device again on it (see Set up a removed device again). From the command line: tressyl-cli identity reset --yes, then pair join.

device_not_revoked

Means: only a device removed from your identity can be set up again; this one is still one of your devices. Do: nothing: it keeps syncing. To take it out, remove it from another of your devices first.

cannot_revoke_self

Means: a device cannot remove itself. Do: remove it from another of your devices (see Manage your devices).

device_not_in_identity

Means: the device named is not one of your devices, or it was removed. Do: check the device on the Devices tab.

peer_not_connected

Means: the other device must be online and connected for this action. Do: turn it on, wait until it shows as connected, then try again.

stamp_key_unavailable

Means: the other device did not provide the key needed to make it a “stamper” (it went offline or did not answer in time). Do: make sure it stays online, then try again.

trust_state_corrupt

Means: the identity file on this device is damaged. Tressyl does not start and does not overwrite it. Do: restore the data folder from a backup if you have one. Do not delete it; ask for help (a recovery action is planned).

device_key_invalid

Means: this device’s own key file is damaged. Tressyl never replaces it silently, since that would make the device a stranger to your others. Do: restore the data folder from a backup, or ask for help.

Folders

folder_marker_missing

Means: the hidden file .tressyl-folder is missing from a synced folder, usually because the disk holding it is not mounted. Tressyl pauses that folder so that an empty mount point is not synced as “everything deleted”. Do: plug in or mount the disk. The folder resumes by itself.

watch_limit_reached

Means: Linux limits how many folders one user can watch for changes, and this limit is reached. Changes are still picked up, but only at the next scan. Do: raise the limit (administrator): echo fs.inotify.max_user_watches=524288 | sudo tee /etc/sysctl.d/60-tressyl.conf then sudo sysctl --system.

folder_config_corrupt

Means: the file listing your synced folders is damaged. Tressyl does not start and does not overwrite it. Do: restore Tressyl’s private folder from a backup, or click Start without this list: see Start again after a damaged folder list.

folder_path_not_accessible

Means: the folder does not exist or cannot be opened. Do: check that it exists and belongs to you.

folder_path_overlap

Means: the folder is inside another synced folder, or contains one. Do: choose a folder that is not inside or around another synced one.

folder_path_not_absolute

Means: the folder was given as a relative path. Do: give its full path (starting with /).

folder_already_exists, folder_not_found

Means: the folder is already synced / is not synced (any more). Do: refresh the list of folders.

folder_label_invalid

Means: the folder name is empty, too long, or contains /, \ or control characters. Do: choose a simple name.

device_label_invalid

Means: the device name is empty, longer than 64 characters, or contains a line break or another control character. Do: choose a shorter name on one line.

folder_assigned

Means: this folder is managed from your devices’ folder list (it was added to this device from another one), so it cannot be changed here directly. Do: change it where it is assigned, from the list of folders per device.

config_limit_reached

Means: a limit is reached: 1024 folders, 256 devices per folder, a folder path longer than 32 KiB, or 1024 removed devices. Do: remove folders or devices you no longer use.

index_corrupt

Means: the list of known files is damaged. Tressyl rebuilds it by scanning your folders again; your files are not touched. Do: nothing; wait for the scan to finish.

invalid_rel_path

Means: a file name received cannot be used safely on this system (for example it would point outside the folder). Do: nothing; the file is skipped. Rename it on the device that has it.

Conflicts

conflict_changed

Means: the files of this conflict changed since the list was shown (edited, deleted, or the conflict was already settled, possibly on another device). Nothing was changed. Do: open the conflict list again and choose again.

conflict_read_only

Means: this device only receives (or only sends) this folder, so a choice made here would not reach your other devices. Do: settle the conflict on a device that both sends and receives this folder.

busy

Means: Tressyl already has several requests waiting for this folder (it is receiving changes). Do: wait a moment and try again.

open_executable

Means: the version you asked to open is a program (it has execute permission). Tressyl does not start programs received from other devices. Do: use Show in folder and look at the file there.

open_failed

Means: your desktop could not open the file or its folder: no app is set up for this kind of file, the desktop portal (xdg-desktop-portal) is missing, or it did not answer. Do: use Show in folder and open the file from your file manager; if neither works, check that xdg-desktop-portal is installed.