Every error by code

When lemonfiber refuses to do something, it says so in four parts: a code, a summary of what happened, what it means for you, and at least one remedy — something to do. The code is the stable part. It is one token, it is never recycled, and it is the thing to search for.

A code looks like VPN-1: a family, then a number. The family says which part of the stack raised it. The number identifies the problem within that family. Each family has a page of its own, and the families below link every one.

There is no code on those pages that lemonfiber cannot raise, and no code it can raise that is missing from them — the tables are read from the revision of lemonfiber this site renders, which is named at the foot of the API reference. A code added to lemonfiber after that revision appears on its family’s page when the revision moves.

How to read a row

Each table gives the code, its severity, the exit a run leaves with when it raises it, what it means when you see it, and what the tool itself offers as the way forward. Where a message includes a name — a service, a path, a port — the tables describe the shape rather than quoting a template.

Two things are worth knowing before you start:

• A problem always states what was and was not changed. Most refusals happen before anything is written. Where something was written, the message says so.
• A problem with no known remedy escalates rather than guesses. Two codes in this reference do that: they ask you for a support bundle rather than offer advice that might be wrong.

The families

Each family’s page sets out all of its codes in one table. Search this site for a code to land on its family’s page directly.

Family	What it covers	Codes
ACK	Answering a warning	1
ADMIT	Who the web interface lets in	14
ASK	Putting a request to the web surface	13
BACKUP	Capturing your configuration	7
BIND	Where the stack is actually listening	3
BUNDLE	The support bundle	8
CONFIG	Your settings	10
CRED	Credentials a service refuses	3
DECLINE	The service that answers an invitation's decline	1
DEVICE	The keys a phone proves the operator with	13
DIAG	Narrowing a diagnosis	1
DOCKER	Talking to the engine	8
ENV	The container engine	5
FORM	Choosing what to run	4
GATE	The request gate	2
GONE	Taking lemonfiber off this machine	3
HANDOFF	Pointing somebody's device at the stack	4
HOST	Keeping a command running without a terminal	6
INVITE	Offering somebody an account	11
KEPT	What lemonfiber keeps here	1
KEY	Keys another program reaches the stack with	13
LIBRARY	What the media server holds	1
LIFE	Starting and stopping	10
MIGRATE	Taking over a setup already here	1
PAIR	Pairing a phone with the stack	5
PLAY	Playing what the household holds	9
PLUGIN	Installing and running plugins	47
PROC	The program underneath	2
PROVIDER	Accounts and indexers	9
QUAL	Quality against what is available	3
QUOTA	What the household may ask for	8
RATE	Holding the stack to a share of the line	6
READ	Asking the web surface a question	16
REHEARSE	Asking what a command would do	2
REISSUE	Letting somebody set a new password	4
REMOVE	Taking somebody out of the household	7
REPAIR	Putting right what the doctor found	3
RESTORE	Putting configuration back	12
SEED	Wiring the services together	4
SERVE	The web surface	8
SETTING	The settings a service reads	6
SETUP	The first run	15
SPACE	The disk, and letting a download go	7
STACK	The stack description	13
STORAGE	The data location	9
TELLING	What the household is told about	1
TUI	The terminal interface	1
UNDO	Putting a run back	4
UPDATE	Moving the stack onto newer versions	5
VPN	Traffic leaving the tunnel	8
WATCH	Guarding the data location	2
WIRE	Choosing what fills a capability	7
WIRING	Drift between services	1
WISH	A member searching for a title and asking for it	13
WORD	The glossary	1

Severity

Every problem carries one of four levels. There are four deliberately: more would not be applied consistently, and inconsistent severity is worse than coarse severity.

Severity	Meaning
advisory	Informational. Nothing is required.
warning	Degraded or risky, and still working.
error	Something is broken.
critical	Consequences outside the machine, or data at risk.

Only five codes are raised as critical: BUNDLE-1, RESTORE-4, SPACE-1, STACK-3 and VPN-1.

Severities are ordered, so a health summary can report the worst of what it found without a comparison table.

State

Alongside severity, a problem says where it stands with respect to being fixed.

State	Meaning
actionable	A remedy is available here, and you can act on it.
guided	You must act, somewhere else — in a service’s own interface, or on the machine.
remediable	lemonfiber can fix this itself. lemonfiber doctor --fix offers it.
unknown	No known remedy. Escalation to a support bundle is offered instead.
suppressed	Acknowledged with --accept, and not led with again until it recurs.

unknown is the honest answer rather than the absent one. Admitting ignorance costs you a support bundle; confident wrong guidance costs you an afternoon.

Exit codes

A script needs to know whether to fix its own input, start Docker, or wait longer, and one code for all three tells it nothing. Every run leaves with one of these.

Exit code	Name	Meaning
0	success	The thing asked for was done, or the question asked was answered.
1	failure	A general failure.
2	usage	A flag or argument you gave could not be understood.
3	preflight	Something outside lemonfiber has to be fixed before it can act.
4	never settled	Something started, and a service never became usable.
5	validation	Something you wrote was refused.

Codes map onto exits deliberately:

• Exit 4: LIFE-1.
• Exit 3: DOCKER-1 and PROC-1, because the engine is not lemonfiber’s to fix.
• Exit 5: CONFIG-1, SETTING-1, SETTING-2, SETTING-3, SETTING-4, STACK-1, STACK-6, STACK-7, STACK-8 and STACK-10, because each is about what you wrote.
• Exit 1: every other code.

Each family’s table gives every code’s severity and exit beside what it means.

Some commands decide their exit from their result rather than from a problem:

• lemonfiber doctor exits 0 when the overall verdict is healthy or degraded, and 1 when it is broken or unknown. Reporting success when nothing could be verified is the falsehood the checks exist to avoid.
• lemonfiber seed exits 5 when a conflict you wrote blocks it, and 1 when work was merely skipped or failed and may complete on a re-run.
• lemonfiber quality set, lemonfiber quality upgrade and lemonfiber reset exit 5 when they are holding a change that needs your confirmation.
• lemonfiber doctor --fix exits non-zero when anything was left unmended.
• Queries — trace, stuck, household, ps, version, forms, config — always exit 0. Asking is never a failure, whatever the answer.

Where these come from

The codes on the family pages are read from lemonfiber’s registry of codes, at the revision this site is pinned to. Every code is declared there once, beside the line saying what it means, and the code that raises it names it from there. A code nothing raises is not declared, and its number is never given to another — so a search that found an answer once finds the same answer later.

lemonfiber publishes the whole registry as contract/codes.json, and every table on these pages is rendered from it. So the sentence at the top of this page holds by construction: a code added to lemonfiber appears on its family’s page when this site’s pin moves, and one it retires goes. This site’s own gate refuses a family with no page, a page for a family the registry does not declare, and a sentence anywhere on the site that names a code nothing raises.

For the model behind them — why a problem cannot be constructed without a remedy, how a typed failure becomes something you read, and why the core never formats — see the error model architecture note. The requirement it is written against is G4, the error and remedy model.