HELP

Troubleshooting

The daemon does not run

tether daemon status
tether daemon start
tether daemon logs -f

On Linux without a systemd user session, use tether daemon start. See Linux and systemd.

macOS asks for App Management

The daemon runs a copy of Tether at ~/.tether/bin/tether. macOS asks once for App Management for this path. Allow it in System Settings > Privacy & Security > App Management. In the file picker, press Cmd+Shift+. to show ~/.tether. Remove old tether rows. See App Management on macOS.

A package from another machine does not install

The package probably waits in the Inbox, is not in this machine's profile, or failed to install.

tether packages inbox                   # held, with a reason
tether packages list --other-profiles   # in another profile
tether packages list                    # failed installs
tether machines list                    # is the source machine trusted?

• If the source machine is not trusted, see Machine trust
• For each reason in the Inbox, see Inbox reasons
• A package that failed to install waits 24 hours before Tether tries it again. See Failed installs
• A package from a 1.x machine waits until you approve it, or until that machine upgrades and you trust it

"Record for <id> fails its signature"

Someone edited that machine's record in the repo, or deleted its .sig file. Tether ignores the record until that machine signs a valid one. Run tether sync on that machine, then check tether machines list.

"key changed" in the Inbox

A trusted machine signed its record with a different key. This happens when that machine made a new signing key under the same id. Compare the fingerprint with tether machines show on that machine before you approve it.

"Cannot read packages/profiles.toml"

The file in the sync repo does not read as TOML. Until you fix it, a sync installs no synced packages, and share, unshare and uninstall stop with an error. Fix the file in the sync repo, or delete it. Without the file, each package belongs to the profiles of the trusted machines that list it.

A config change comes back

A 1.x machine before 1.13.2 can push its old copy of config.toml and revert your change. Patch or upgrade the 1.x machines, then make the change again. When two 2.0 machines change one setting, each keeps its own value and the sync warns. They settle within two syncs. See Config merge.

A file has a conflict

tether resolve

For files that an app rewrites on every machine, set an on_conflict rule. See Conflicts.

A sync seems stuck

Without a terminal, git commands that reach the remote stop after 5 minutes, and the next sync tries again. In a terminal, ssh can wait for a passphrase or a host key. Check the terminal for a prompt.

Encryption problems

tether unlock                         # enter your passphrase
ls ~/.tether/sync/encryption.key.age  # the encrypted key exists?

"Team push blocked" stops a sync

tether sync stops with "Team push blocked: <file> contains <n> secret(s)". The daemon logs the same line. Remove the secret from the file, or add an ignore pattern for a false positive:

tether ignore secrets add 'MY_SAFE_PATTERN='

Start over on one machine

tether daemon uninstall
rm -rf ~/.tether
tether init

Uninstall the daemon first. launchd and systemd restart a stopped daemon, and it would then run while you delete its files.

This deletes the machine's id, signing key, trust list, backups and age identity. Without the age identity, this machine cannot read team secrets until a teammate adds its new public key. Tether makes a new id and a new key. Your other machines see a new machine and must trust it. Remove the old record with tether machines remove <old-id>. This machine must trust your other machines again.