Error codes

When a computer refuses something, it answers with one of 29 error codes. The same numbers close a connection (as QUIC application close codes; 0 means no error). The phone turns each code into a plain sentence with the computer’s name in it.

Wire error codes

Number	Code	Meaning	What the phone says (for a computer named Studio PC)
1	Malformed	A message that does not parse, has the wrong version, or a bad parameter	Studio PC could not read the request. Update Tealhand on this phone and on Studio PC.
2	VersionTooOld	The two sides’ protocol versions do not overlap	This phone and Studio PC run versions of Tealhand that are too far apart. Update the older one.
3	NotOnRoster	The sender is not on the computer’s device list (or its entry expired)	Studio PC does not know this phone any more. Connect them again.
4	BadSignature	A missing or invalid signature	Studio PC could not verify the signature from this phone. Connect them again if this keeps happening.
5	Expired	Out of date, issued in the future, issued before the computer’s Host started; also a timeout	Studio PC refused the request as out of date. Check that the date and time are right on this phone and on Studio PC.
6	Replay	The computer has already seen this command	Studio PC had already seen that request. Try again.
7	PresenceRequired	The action needs a fingerprint or PIN signature, and there was none. From another computer: a terminal or a saved command the owner marked for the fingerprint, without the phone’s approval (an older computer that doesn’t ask)	Studio PC needs your fingerprint or PIN for this, and did not get it.
8	RemoteControlOff	Remote control is off and the action is not a read or a cancel	Remote control is off on Studio PC. Turn it on at the computer.
9	OtherUserSignedIn	Another user is signed in, so the computer will not sleep or shut down	Someone else is signed in on Studio PC, so it did nothing.
10	TaskNotFound	The program a rule should watch is not running	Studio PC cannot find that program.
11	NotAllowed	Not allowed from here: a local-only action from a phone, the wrong target, an unknown rule, no GPU for a GPU rule, a device list that adds a phone	Studio PC does not allow that. For a read only folder: Studio PC shares this folder read only, so nothing in it can change. For a terminal or saved command when Tealhand Host runs as administrator: Studio PC runs Tealhand Host as administrator, so it won’t run terminals or commands. Start it as a normal user there.
12	Busy	Too many requests or nonces, a notice already running, too many rules, or the helper already running	Studio PC is busy. Try again in a moment. For a terminal: Two terminals are already open on Studio PC. Close one, then try again. For a saved command: Studio PC is already running this command, or four others. Wait for one to end, then try again.
13	Internal	Something failed on the computer (for example the power helper is missing or could not tell who is signed in)	Something went wrong on Studio PC.
14	NoGpu	A GPU rule on a computer with no GPU that Tealhand can watch	Studio PC has no graphics card that Tealhand can watch, so it cannot wait for the GPU to be idle.
15	TooManyRules	The computer already keeps as many rules as it can	Studio PC already has as many rules as it can keep. Cancel one before adding another.
16	TooLate	A cancel that came after the shutdown or sleep started	It was too late to cancel: the shutdown or sleep on Studio PC had already started.
17	NotFound	A file, folder, download, terminal or saved command that is not there (any more)	For a file or folder: Studio PC can’t find that file or folder. It may have been moved or deleted. Go back and open it again. For a download: Studio PC has no such download any more. Refresh the list. For a saved command or terminal: Studio PC has no such saved command or terminal any more. Refresh the list, then try again.
18	Exists	The name is already taken	Something with that name is already there on Studio PC. Choose another name.
19	PathRefused	A path that leaves the shared folder, goes through a link, or breaks the name rules	Studio PC refused that path: it leads outside the shared folder or through a link. Open it from the shared folder.
20	TooLarge	A file over the limit, or a folder too big to list	For a download: The file is larger than Studio PC allows for a download. Otherwise: That is too large for Studio PC to take.
21	NoSpace	Less than 1 GiB would stay free on the disk	Studio PC is running out of disk space. Free some space there, then try again.
22	AddressRefused	A download link that is not allowed, or that leads to a private network	Studio PC will not download from that address: it leads to a private network. Use a public web link.
23	FetchFailed	A download that could not be fetched	Studio PC could not download that. Check the link and try again.
24	NotSetUp	The owner has not set this up on the computer: no shared folder, no shared folder that is not read only for a download, SSH access off, or an action this Host does not run yet	For files: No folder is shared on Studio PC yet. Share a folder on the computer, then try again. For downloads: No downloads folder is set up on Studio PC. Share a folder there and allow downloads into it. (The phone usually shows “No writable folder on Studio PC” first: see below.) For SSH access: SSH access is off on Studio PC. Switch it on at the computer: in Tealhand there, or with tealhand-host ssh on. Otherwise: Studio PC is not set up for that yet. Set it up at the computer, or update Tealhand on it.
25	Unsupported	The computer’s system can’t do it, for example it has no trash to delete into	Studio PC cannot do that: its system does not support it.
26	Declined	Version 9: the owner declined, on the phone, another computer’s terminal or fingerprint command	(on the computer that asked) Declined on your phone, so Studio PC did nothing.
27	NoPhone	Version 9: no phone that can approve is connected to the computer	(on the computer that asked) Approve it on your phone: it must be online. Open Tealhand on your phone, then try again.
28	NoAnswer	Version 9: the phone didn’t answer within a minute	(on the computer that asked) Your phone didn’t approve it in time, so Studio PC did nothing.
29	Mismatch	Version 10: a sent file’s SHA-256 differs from what arrived; nothing was kept	The copy on Studio PC arrived damaged, so it was not kept. Send it again. (The copy is first sent once more by itself.)

Inside a Response message, a code is encoded as its position in the list (number minus 1). The phone’s app layer reports the number (1 to 29).

“In Tealhand there” means the Tealhand app on the computer: Settings → Shared folders shares a folder and sets the default for downloads, and Settings → SSH access switches SSH access on. On a computer without a screen, use the command line: tealhand-host share add <path> shares a folder, --downloads makes it the default for downloads, and tealhand-host ssh on switches SSH access on (Share folders).

A computer also refuses by closing the connection with one of these codes, for example NotOnRoster after it forgot the phone, or VersionTooOld when the versions do not overlap. The phone keeps that reason: it shows the same sentence as in the table, with the computer’s name when it knows it, and sets the computer’s link state to forgotten (NotOnRoster: connect again) or incompatible (VersionTooOld or a version problem: update the older side). A close with Expired (an idle or slow connection) or Busy (too many connections) is an ordinary end: the phone reconnects quietly.

Rule refusal reasons

A rule that fires and is refused carries a reason, in RuleRefused events and in the rule’s state. The phone shows a notice titled “Studio PC refused the rule” with this text:

Value	Reason	The notice says
0	OtherUserSignedIn	Another user is signed in on the computer, so the rule did nothing.
1	TaskNotFound	The program the rule watches isn’t running, so the rule did nothing.
2	RemoteControlOff	Remote control is off on the computer. Turn it on at the computer itself.
none	a reason this version does not know	The computer gave a reason this version of Tealhand doesn’t know. Update Tealhand on this phone.

Errors when connecting on the phone

Situation	What the phone says
Not a Tealhand QR code	That is not a Tealhand connection code
The QR code expired	That code has expired: show a new one on the computer
The computer answered from a different key than the QR named	That is not the computer the code was made for. Nothing was sent.
The computer’s proof did not match	The computer could not prove it is the one that showed the code. Nothing was changed.
The computer said no, or the person at it cancelled	The computer did not accept the connection. Nothing was changed.
The computer belongs to another owner	That computer already belongs to another Tealhand owner. Forget the old phone on it first.
A step came out of order or too late	Connecting ended. Start again.
You tapped “They don’t match”	Connecting stopped. The codes were different, so nothing was connected: another device may be in between. Make a new code on the computer, then scan it again.
The camera is not allowed	Tealhand isn’t allowed to use the camera. Allow it in Android settings, or paste the code instead.
The phone has no usable camera	This phone has no camera Tealhand can use. Paste the code.

Messages from the app itself

Situation	What the phone says
Part of the app is missing	Tealhand can’t start because part of the app is missing. Reinstall Tealhand.
The key store did not answer at start	The phone’s key store didn’t answer. Restart the phone, then try again. A support code follows on its own line.
Android reset the keys (screen lock removed)	Android reset this phone’s Tealhand keys, which happens when the screen lock is removed. … Reset Tealhand on this phone, then connect it again. On each computer, forget this phone in Tealhand there (or run tealhand-host unpair).
A computer forgot this phone	This computer forgot this phone and no longer accepts its commands. Connect again to use it.
The versions can’t work together	This computer and this phone run versions of Tealhand that can’t work together. Update Tealhand on the older one, then open the app again.
A card could not be sent (an app failure)	Tealhand couldn’t send this. Nothing was done. Try again.
A card was sent while reconnecting	Tealhand is reconnecting. Try again in a moment.
A card expired	This request expired. Ask again.
A shutdown or sleep did not start	Tealhand Host couldn’t start the shutdown or sleep. Check the computer, then try again from Power.
The Power page of an offline computer	Offline · last seen 14:02. Actions are off while the computer is offline. Its rules still run on it.
Another of your computers changed something (a notice, in the Inbox and in Chat)	Studio PC deleted a.txt on Cloud PC. Another of your computers did this. If you did not, remove that computer in Devices. (Hold it for Remove Studio PC.)
A countdown cancelled by another computer	Cancelled from another computer
Chat: no computer connected	No device is connected yet. Connect one, then ask again.
Chat: remove or rename	Chat can’t remove or rename a device. Open the device and do it there.
Chat: cancel a rule	Chat doesn’t cancel rules. Pick the rule to cancel on the Power page.
Chat: something only the computer changes	Chat can’t change this. Change it at the computer itself.
Chat: a command that doesn’t exist	There is no such command. Type / to see them.
Chat: /settings chat planner with no planner address saved	Set the planner address first. It opens now.
A download on a computer with no shared folder that is not read only	No writable folder on Studio PC. On Studio PC, open Tealhand → Settings → Shared folders and share a folder that is not read only. Or, without a screen, run: tealhand-host share add ~/Downloads --downloads (buttons: How to set it up, Check again)
Check again and there is still none	Studio PC still shares no writable folder.
A download link that is a web page with no file on it	example.com sent a web page, and Studio PC found no file on it. The site may need a sign-in, a script or a countdown, which Studio PC can’t do. In your browser, press and hold the site’s Download button and share that link, or download it on this phone and share the file to Tealhand.
Adding a saved command while SSH access is off	Adding commands from here needs SSH access on.
An empty address field	Enter an address.
An address without https://	Use an address that starts with https://.
An address that is not a web address	This isn’t a web address. It should look like https://relay.example.com.
An address with a name or password in it	This address has a name or password in it. Remove them.
A certificate fingerprint that is not sha256: and 64 hex digits	This isn’t a certificate fingerprint. It is sha256: followed by 64 characters, 0 to 9 and a to f.
Saving your own relay	Tealhand can’t test the relay from here yet. If it is unreachable, Home will say so.

A locked phone shows only “News from one of your computers”: no device, program or rule name.

Other phone messages

Situation	What the phone says
The computer is not reachable	the device is not reachable right now
The computer took too long	it took too long
You dismissed the fingerprint or PIN prompt	cancelled
The key store could not sign	the phone’s key store could not sign
The phone’s saved data belongs to another identity	this phone’s saved connections belong to another identity
A card was confirmed too late (over 5 minutes)	this card has expired: ask again
A server address that is not allowed	a server address must start with https:// (plain http works only for a computer on your own network)
The relay refused the owner	the relay does not accept this phone as an owner
A relay address that is not https://	the relay’s addresses must start with https://
The relay holds a newer device list, and the phone already signed again once for this change	the relay holds a newer device list than this phone
The relay claims a device list more than 8 versions ahead of the phone	The relay claims to hold a newer device list than this phone. Check the relay, or connect this phone to your computers again.
The relay sent a 409 the phone cannot read, or refused the upload for another reason	the relay’s answer was not understood, or the relay refused the device list
A device list upload failed	“Could not update the relay’s device list:” and then the reason above
A computer did not get a new device list	“ did not get the new device list. It will be sent again when it is back online.”
An edit while a phone is still connecting	A phone is still connecting to a computer. Finish or cancel that, then try again.
Too many cards open at once (16)	too many open cards: confirm or dismiss one first
A second copy of the app uses the same data	Tealhand’s data on this phone is already in use by another running copy of the app
The computer’s version cannot talk to this phone’s	this phone and the computer run versions of Tealhand that cannot talk to each other; update the older one

Planner and relay HTTP answers

The planner answers 200, 400, 429, 503 or 504 (Self-host the planner). The relay’s upload answers 200, 400, 403, 404, 405, 409, 413, 429 or 500 (Run your own relay). On the phone, a planner answer becomes a plan, or one of these lines, and chat carries on with word matching on the phone:

Outcome	What the phone says
No planner set up	No planner is set up. Using word matching on this phone.
Refused	The planner refused the request. Using word matching on this phone.
Too many requests	The planner is busy. Using word matching on this phone.
Unavailable	The planner isn’t available. Using word matching on this phone.
Too slow	The planner took too long. Using word matching on this phone.
Not reachable	Can’t reach the planner. Using word matching on this phone.

Command-line errors and exit codes

tealhand-host, tealhand-relay and tealhand-planner print every error as two lines on stderr: error: and what happened, then what to do. For example:

error: the relay address must start with https://
Use --relay disabled, public, or your relay's address (https://...).

The ones you may meet, with the command that gives them:

error: line	Command	What to do
Tealhand Host is already running for this data folder: quit it first	connect, unpair, remote off, share, ssh, commands	Stop the running Host or the Tealhand app first, or pass another --data-dir. downloads doesn’t need this: it works while the Host runs
--relay-pin needs --relay	connect, run	Add your relay’s address with --relay https://..., or leave --relay-pin out
the certificate fingerprint is not sha256: followed by 64 hex digits	connect, run	Copy it from tealhand-relay fingerprint, for example --relay-pin sha256:3f0c...
a certificate fingerprint works only with your own relay's address	connect, run	Use --relay https://... with --relay-pin, or leave --relay-pin out
the port must be a number from 1 to 65535	connect, run	Use --port 41234, or leave it out to keep the port used last time
share add needs a folder, share remove needs the folder's number, share needs list, add or remove	share	Run tealhand-host share list, share add <path>, share remove <id> or share default <id>
share default needs a folder's number, or none	share default	Run tealhand-host share list to see the numbers, then share default <id> or share default none
ssh needs on or off	ssh (or terminal)	Run tealhand-host ssh on or tealhand-host ssh off
downloads cancel needs the download's number, downloads takes list or cancel <id>	downloads	Run tealhand-host downloads to see the numbers, then tealhand-host downloads cancel <id>
download N is not running or paused	downloads cancel	Run tealhand-host downloads to see the numbers. Only a running or paused download can be stopped
that folder was not found	share add	Check the path; it must be a folder, not a file
that folder can't be shared	share add	Share a folder of your own: not a whole drive, a system folder, Tealhand’s data folder, a link, or a folder inside or around one that is already shared
that folder is already shared, or another one is the default for downloads	share add, share default	Run tealhand-host share list to see what is shared; share default <id> moves the default
that name or path can't be used	share add	Give a name of 1 to 64 characters; --downloads (the default for downloads) needs a folder that is not --read-only
too many folders are shared	share add	Stop sharing one first with tealhand-host share remove <id>
no shared folder has that number	share remove	Run tealhand-host share list to see the numbers

When connecting ends without a phone, tealhand-host connect prints “Connecting cancelled. Nothing was changed.” when you answered no, or one of: error: connecting took too long and stopped (run it again for a new code), error: this computer is connected to another owner's phone (run tealhand-host unpair first, then tealhand-host connect), error: connecting didn't finish (run it again for a new code).

Exit code	Meaning
0	Done, or stopped with Ctrl-C or SIGTERM
1	Failed while running (for example a port in use, connecting that did not finish)
2	Wrong command, option or setting: fix the command line or the config file