Look up a diagnostic by symptom

Human-readable check output carries no diagnostic codes. All you get is file:line: message. When what you have in hand is that message — or nothing but a feeling that something is off — start here.

If you already have a code, the diagnostic code index is faster.

Get the code

--json prints the same diagnostics with their codes.

koyu check bad.muro --json

[
 {
  "code": "SUF01",
  "severity": "error",
  "message": "The ceiling height of /L1/a cannot be determined (neither the space's h: nor level L1's h: is there)",
  "line": 4,
  "file": "<absolute path>/noh.muro",
  "path": [
   "/L1/a"
  ]
 }
]

message is the body only — no position prefix. The position lives in line and file. The full reading procedure is on Reading a diagnostic.

There are only two severities. error means the composition does not stand (exit code 1); warning means it stands but is suspect (exit code 0, or 1 under --strict). Severity is an invariant property of the code and never varies by case.

1. check stops with an error

Message bodies can be searched for verbatim. Below are fragments of them.

What you see	Cause	Fix	Code
Undefined grid line name: X1	No grid, or it sits after the line that uses the grid reference	Write grid X and grid Y before the first line that uses them → Common traps	composition error
A region is given as two ranges, X?..X? and Y?..Y?	Almost always the type (second positional argument) is missing, so the first half of the region is read as the type	Write space <path> <type> X?..X? Y?..Y? in that order → Common traps	composition error
has a region, but its level cannot be determined	There is no level line. Writing /L1/ in the path does not declare a level.	Write level L1 0 h:2400 slab:150 before the lines that use it	SUF02
The ceiling height of … cannot be determined	Neither the space's h: nor the level's h: exists	Write h: on one of them	SUF01
The spaces do not touch, so no boundary can be derived	They meet only at a corner. Touching requires a shared edge with length	Extend one rectangle so an edge is shared, or delete the boundary line → Common traps	BND04
There is more than one boundary segment; pick an edge with edge:N/E/S/W	The boundary to the exterior falls on several edges of the room's perimeter	Pick the edge on the opening with edge:. N=+Y / S=−Y / E=+X / W=−X	OPN05, or SEG05 for seg
No boundary segment can hold the door	That pair of spaces has no boundary segment at all	Check with koyu graph whether they really touch	OPN04
Space regions overlap:	A space with a region has a child space with a region	Make the parent a zone → Counted and uncounted divisions	GEO02
Regions within … overlap:	Rectangles unioned with + inside one space overlap each other	Split them so they do not	GEO01
References an undefined space:	A misspelled path, or the layer declaring that space is not imported	Fix the path or add the import	REF01
Duplicate boundary:	Two boundaries on the same pair of spaces	Merge them into one, or give both an edge: limiting them to different edges	BND02
A wall boundary cannot be written to a space on a different level	A relation across storeys written as a wall	Use type:stair / type:shaft / type:void	BND03
Openings overlap	A door and a window sit too close on the same boundary segment	Move one with at:	OPN02
The door width … exceeds the boundary segment length	The opening is longer than the wall	Narrow it, or lengthen the wall	OPN06
is written as a positive number:	An interpreted attribute's value does not read as a number (h:24OO has letters in it)	Fix the spelling	ATT01
A boundary type is wall / open / stair / shaft / void:	A value outside the ledger on an attribute with a fixed vocabulary	Use a word from the ledger	ATT02
which is not in the ledger (check the spelling, or add a namespace…)	An attribute key not in the ledger, with no namespace. nmae: does not pass silently	Fix the spelling, or add a namespace such as acme.note: if the value is only carried	ATT03
daylight is either 1 … or 0	Something other than 0 or 1 on daylight:	Write daylight:1 or daylight:0	DAY01
Duplicate uid:	The same uid on two targets	Replace one with a fresh value from new_uids → Identity	UID03
A koyu 0.5 file uses a 1.0 word:	A newer word (over, drop, set editing) in a file declaring an older version	Raise it to koyu 1.0	VER04
One layer holds two opinions about …	One layer holds two opinions about one attribute	Override from another layer → Lay measurements over the plan	composition error
No such target for over:	The target of over was never composed	Fix the spelling, or place it after the layer that defines it	composition error
Duplicate space path:	Two layers define the same path	Turn one into an over, or split the paths	composition error

2. check emits warnings only

The exit code stays 0 unless you pass --strict. Some of these mean nothing gets generated.

What you see	What it means	What to do	Code
has no slab:, so not one floor is generated on this storey	No floor is produced on that level	Write slab:, as in level L1 0 h:2400 slab:150	SUF03
There are no spaces beneath zone …	The zone has no members; the path prefix does not line up	Fix either the zone path or the space paths	ZON01
A space shares its path with a zone	Both a space and a zone occupy the same path	Settle on one of them	ZON02
A door on a vertical boundary is not interpreted	An opening written on a stair, shaft or void boundary. It has no effect on passage	Delete it. Passage is carried by the vertical boundary itself	VRT05
A door on an open boundary has no effect on passage	type:open is already passable	Delete the opening, or make the boundary a wall again	OPN03
cuts nothing	The drawn line matches the default adjacency line, or falls outside the allocation	Redraw it, or delete it	LIN03
The area spills outside the region of	An area runs past its parent space	Shrink its extent → Counted and uncounted divisions	SEG02
No column stands for a column declaration	There is no floor at that grid crossing, or the space is semi-outdoor with no floor above	Revisit the declared grid lines, or the extent with a floor	COL01

3. check is green and it is still wrong

There is no diagnostic here. check speaks only to whether what is written contradicts itself as data. Whether it works as a building is not its subject.

Symptom	Cause	Tool to confirm with
A room cannot reach the outside	The default between touching spaces is a wall with no door. Doors are never added automatically	koyu doors / koyu graph → Common traps
No envelope at all	Nothing is derived against a space with no region (/out)	envelope.gap from koyu validate → Common traps
An empty file is green	A composition with nothing written in it stands	Look inside with koyu stats / koyu graph
A room you want in the area schedule is missing	area is an uncounted division. It appears in neither area nor room count	Counted and uncounted divisions
The boundary count from check and boundaries in the canonical JSON disagree	check counts the composed model; canonical JSON carries only what was written	Not a contradiction → Common traps
An attribute has no effect	An unknown key is an error, but a misspelled value is carried	Trace the origin with koyu layers --attrs
Changing the type does not change the daylight verdict	Daylight scope is decided by daylight:1, not by the type	koyu light

4. check says nothing — validate does

Architectural judgement comes back separately from koyu validate. It carries chapter.rule spellings, not check codes.

Symptom	Rule
Part of the perimeter faces nothing	envelope.gap
Window area falls short of 1/7 of the floor	daylight.ratio
A window has no h:, so the window area is incomplete	daylight.unknown
Stair treads are cramped, or riser and tread fall outside the usual band	stair.proportion
A ramp is steeper than declared	run.slope
A vertical run has form but nothing connects the storeys	run.disconnected
A room cannot reach the exterior	access.unreachable
A door opens only onto a void	access.voidonly
A column stands in a door	column.blocksdoor
The building escapes the site shape	site.escape
Declared and derived site area disagree	site.area
Road frontage is too short	site.frontage

Every rule is on Judgement — koyu validate.

5. The command itself fails

What you see	Exit code	Cause
Undeclared level: l2 (declared: L1 L2 R)	2	A wrong level name after -l. Case matters. Confirm with koyu levels
The Usage: koyu … line	2	Missing arguments. --help goes down the same path
Error: No level is defined with a stack trace	1	There is no level line at all. check can be green while drawing fails
Error: There is no space with a region on level R with a stack trace	1	No space on that level has a region
Cannot reach /out from /L1/nope	1	Unreachable. The same wording appears when the start or end path does not exist. Confirm the spelling with koyu graph

A problem with how you called it exits 2; a problem with the composition exits 1. The two are never mixed, so CI can treat them differently.

Related

• Common traps — the entries above that need a worked fix
• Diagnostic code index — all 65, looked up by code
• Reading a diagnostic — the structure of the --json return
• Judgement — koyu validate — the fifteen rules
• The scope of the promise — what a green check means