This page is generated from docs/error-codes.md — edit it there.

ArchLang error codes

Every diagnostic carries a stable code. Look one up with arch explain <CODE> (e.g. arch explain E_ROOM_SIZE). Errors abort rendering; warnings do not.

34 errors · 24 warnings

Code	Severity	Summary
E_ARGCOUNT	error	Component called with the wrong number of arguments.
E_ARITY	error	Built-in function called with the wrong number of arguments.
E_ASSIGN_UNDEF	error	Assignment to an undeclared name.
E_CALL_DEPTH	error	Value-function call stack too deep.
E_COLUMN_SIZE	error	Column must have a positive size.
E_DIV_ZERO	error	Division or modulo by zero.
E_DOMAIN	error	Math domain error.
E_DOOR_WIDTH	error	Door must have a positive width.
E_DUP_ID	error	Duplicate element id.
E_FURN_AGAINST	error	Invalid against wall fixture placement.
E_FURN_ROOM	error	Furniture placed in an unknown room.
E_FURN_ROTATE	error	Furniture rotation must be a quarter-turn.
E_FURN_SIZE	error	Furniture must have a positive size.
E_IMPORT_BAD_SPEC	error	Malformed import spec.
E_IMPORT_CONFLICT	error	Imported name conflicts with an existing component.
E_IMPORT_CYCLE	error	Cyclic import.
E_IMPORT_NOT_EXPORTED	error	Imported name is not exported by the module.
E_IMPORT_NOT_FOUND	error	Import path could not be resolved.
E_IMPORT_PARSE	error	Imported module has a parse error.
E_INDEX	error	Array index out of range.
E_LAYOUT_CYCLE	error	Relational room placement forms a cycle.
E_LAYOUT_REF	error	Relational placement references an unknown room.
E_OPENING_WIDTH	error	Opening must have a positive width.
E_RANGE_LIMIT	error	Range too large.
E_RECURSION	error	Component recursion too deep.
E_REDEF	error	Name already defined in this scope.
E_ROOM_SIZE	error	Room must have a positive size.
E_TYPE	error	Type mismatch.
E_UNKNOWN_COMPONENT	error	Unknown component.
E_UNKNOWN_FN	error	Unknown function.
E_UNKNOWN_REF	error	Unknown reference.
E_WALL_THICKNESS	error	Wall must have a positive thickness.
E_WHILE_LIMIT	error	while exceeded its iteration cap.
E_WINDOW_WIDTH	error	Window must have a positive width.
W_BATH_VIA_BEDROOM	warning	Bathroom is reachable only through a bedroom.
W_BEDROOM_NO_WINDOW	warning	Bedroom has no window.
W_DOOR_CLEARANCE	warning	Door is narrower than the minimum clear width.
W_DOOR_OFF_WALL	warning	Door does not lie on any wall.
W_EMPTY_PLAN	warning	Empty plan.
W_FIXTURE_FLOATING	warning	A plumbing/kitchen fixture is not against a wall.
W_FIXTURE_WRONG_ROOM	warning	Fixture sits outside its declared room.
W_FURN_CLEARANCE	warning	A fixture's use-space is blocked.
W_FURNITURE_OVERLAP	warning	Two pieces of furniture overlap.
W_HATCH_SCALE	warning	Hatch scale must be positive; using 1.
W_NO_ENTRANCE	warning	The plan has no exterior door.
W_OPENING_OFF_WALL	warning	Opening does not lie on any wall.
W_ROOM_DISCONNECTED	warning	Room has no door — it can't be entered.
W_ROOM_NO_FIXTURE	warning	Bathroom or kitchen has no fixtures.
W_ROOM_NOT_ENCLOSED	warning	Bathroom is not fully enclosed.
W_ROOM_OVERLAP	warning	Rooms overlap.
W_ROOM_TOO_SMALL	warning	Room is implausibly small.
W_ROOM_UNREACHABLE	warning	Room cannot be reached from the entrance.
W_SANITIZED_CONFIG	warning	A disallowed config value was stripped.
W_SWING_OBSTRUCTED	warning	Door swing is obstructed.
W_UNKNOWN_MATERIAL	warning	Unknown wall material; using the default hatch.
W_UNKNOWN_STYLE_KEY	warning	Unknown style key.
W_UNKNOWN_THEME_KEY	warning	Unknown theme key.
W_WINDOW_OFF_WALL	warning	Window does not lie on any wall.

E_ARGCOUNT

error — Component called with the wrong number of arguments.

Cause. A component instance supplies more or fewer arguments than the component declares parameters.

Fix. Pass exactly one argument per declared parameter.

component bed(x, y) { … }
bed(300)        # error: expects 2 arguments

E_ARITY

error — Built-in function called with the wrong number of arguments.

Cause. A built-in (e.g. abs, sqrt, len) was called with the wrong argument count.

Fix. Check the function's arity; most built-ins take one argument.

let x = abs(1, 2)   # error: abs expects 1 argument

E_ASSIGN_UNDEF

error — Assignment to an undeclared name.

Cause. NAME = value was used for a name never introduced with let.

Fix. Declare it first with let, or fix a typo in the name.

x = 5           # error: declare with `let x = …` first

E_CALL_DEPTH

error — Value-function call stack too deep.

Cause. A value-function recurses (directly or mutually) beyond the call-depth limit.

Fix. Make the recursion terminate, or rewrite it iteratively with a bounded while.

let f(n) = f(n + 1)   # error: never terminates

E_COLUMN_SIZE

error — Column must have a positive size.

Cause. A column's width or height evaluated to zero or a negative number.

Fix. Give the column a positive size W x H.

column at (0,0) size 0x300   # error: width is 0

E_DIV_ZERO

error — Division or modulo by zero.

Cause. An expression divides (or takes a remainder) by a value that evaluates to zero.

Fix. Guard the divisor, or use a non-zero value.

let x = 10 / 0   # error

E_DOMAIN

error — Math domain error.

Cause. A built-in received an out-of-domain argument (e.g. sqrt of a negative number).

Fix. Pass a value within the function's domain.

let x = sqrt(-1)   # error

E_DOOR_WIDTH

error — Door must have a positive width.

Cause. A door's width evaluated to zero or a negative number.

Fix. Give the door a positive width.

door at (0,0) width 0   # error

E_DUP_ID

error — Duplicate element id.

Cause. Two elements declare the same id=…; ids must be unique across the plan.

Fix. Rename one of them, or drop the explicit id to auto-generate a unique one.

room id=a at (0,0) size 1x1
room id=a at (1,0) size 1x1   # error: duplicate id "a"

E_FURN_AGAINST

error — Invalid against wall fixture placement.

Cause. A wall-anchored fixture references an unknown wall, omits segment on a multi-segment wall, omits side, sits on a non-axis-aligned segment, has an out-of-range offset, or also sets rotate. The compiler will not guess which wall/side/segment was meant.

Fix. Name an existing wall id, add segment <n> for multi-segment walls, give side left|right, keep the segment axis-aligned, and drop any explicit rotate.

furniture wc against wall w1 side left size 400x700   # error if w1 is unknown or multi-segment

E_FURN_ROOM

error — Furniture placed in an unknown room.

Cause. A furniture item names a room with in <roomId>, but no room has that id.

Fix. Use the id of an existing room id=…, or drop the in clause.

furniture bed at (0,0) size 1500x2000 in bedrm   # error: no room id=bedrm

E_FURN_ROTATE

error — Furniture rotation must be a quarter-turn.

Cause. A furniture item's rotate is not one of 0, 90, 180, or 270 degrees.

Fix. Use a quarter-turn: rotate 0|90|180|270.

furniture wc at (0,0) size 400x700 rotate 45   # error: not a quarter-turn

E_FURN_SIZE

error — Furniture must have a positive size.

Cause. A furniture item's width or height evaluated to zero or a negative number.

Fix. Give the item a positive size W x H.

furniture bed at (0,0) size 0x2000   # error

E_IMPORT_BAD_SPEC

error — Malformed import spec.

Cause. The string after import is not a recognizable module reference.

Fix. Use a relative path ("lib/x.arch") or a namespaced spec ("@scope/name:1.0.0").

import "???" : a   # error

E_IMPORT_CONFLICT

error — Imported name conflicts with an existing component.

Cause. An imported component has the same name as one already defined or imported.

Fix. Rename with as, or remove the duplicate.

import "lib.arch": bed as lib_bed

E_IMPORT_CYCLE

error — Cyclic import.

Cause. Modules import each other in a cycle, which cannot be resolved.

Fix. Break the cycle so module dependencies form a tree.

# a.arch imports b.arch which imports a.arch  → error

E_IMPORT_NOT_EXPORTED

error — Imported name is not exported by the module.

Cause. The module has no component with the requested name.

Fix. Import a name the module actually defines (check its components).

import "lib.arch": nope   # error if lib.arch has no `component nope`

E_IMPORT_NOT_FOUND

error — Import path could not be resolved.

Cause. The World could not read the module at the given path.

Fix. Check the path (relative to the importing file) and that the file exists.

import "lib/missing.arch": a   # error

E_IMPORT_PARSE

error — Imported module has a parse error.

Cause. The module referenced by import does not itself parse.

Fix. Fix the syntax error in the imported module.

# error originates in the imported file

E_INDEX

error — Array index out of range.

Cause. arr[i] used an index outside 0 .. len(arr) - 1.

Fix. Clamp or check the index against len(arr).

let a = [1, 2]
let x = a[5]   # error

E_LAYOUT_CYCLE

error — Relational room placement forms a cycle.

Cause. Rooms placed with right-of/below/… reference each other in a loop, so no order resolves them.

Fix. Break the cycle by giving one of the rooms absolute at (x,y) coordinates.

room id=a right-of b size 100x100
room id=b left-of a size 100x100   # error: a ↔ b cycle

E_LAYOUT_REF

error — Relational placement references an unknown room.

Cause. A right-of/below/… clause names a room id that does not exist in the plan.

Fix. Reference an existing room id, or fix the typo.

room id=k right-of ghost size 100x100   # error: no room "ghost"

E_OPENING_WIDTH

error — Opening must have a positive width.

Cause. A cased opening's width evaluated to zero or a negative number.

Fix. Give the opening a positive width.

opening at (0,0) width 0   # error

E_RANGE_LIMIT

error — Range too large.

Cause. A lo..hi range would expand to more elements than the safety cap allows.

Fix. Use a smaller range, or restructure to avoid materializing it.

for i in 0..1000000 { … }   # error: range too large

E_RECURSION

error — Component recursion too deep.

Cause. Component instantiation nested beyond the depth limit (usually unbounded self-instantiation).

Fix. Add a base case so the recursion terminates.

component r(n) { r(n) }   # error: never terminates

E_REDEF

error — Name already defined in this scope.

Cause. A let re-declares a name already bound in the same scope.

Fix. Rename one binding, or use NAME = … to reassign instead of redeclaring.

let x = 1
let x = 2   # error: redefinition

E_ROOM_SIZE

error — Room must have a positive size.

Cause. A room's width or height evaluated to zero or a negative number.

Fix. Give the room a positive size W x H.

room at (0,0) size 0x4000   # error: width is 0

E_TYPE

error — Type mismatch.

Cause. A value was used where another type was required (e.g. a string where a number is expected, or a non-array in for).

Fix. Convert or supply the expected type.

room at (0,0) size "big" x 10   # error: size needs numbers

E_UNKNOWN_COMPONENT

error — Unknown component.

Cause. An instance calls a component name that is not defined or imported.

Fix. Define the component, import it, or fix the name (see the suggestion hint).

sofa(0, 0)   # error if no `component sofa` is in scope

E_UNKNOWN_FN

error — Unknown function.

Cause. A call uses a name that is neither a built-in nor a value-function in scope.

Fix. Define it with let f(…) = …, or fix the name.

let x = frobnicate(2)   # error

E_UNKNOWN_REF

error — Unknown reference.

Cause. An expression references a name that is not bound in scope.

Fix. Declare it with let, pass it as a parameter, or fix the typo.

let x = y + 1   # error if `y` is undefined

E_WALL_THICKNESS

error — Wall must have a positive thickness.

Cause. A wall's thickness evaluated to zero or a negative number.

Fix. Give the wall a positive thickness.

wall exterior thickness 0 { (0,0) (1,0) }   # error

E_WHILE_LIMIT

error — while exceeded its iteration cap.

Cause. A while ran more times than the safety cap allows (usually a condition that never becomes false).

Fix. Ensure the loop body updates a binding so the condition eventually fails.

let i = 0
while i < 1 { column at (0,0) size 1x1 }   # error: i never changes

E_WINDOW_WIDTH

error — Window must have a positive width.

Cause. A window's width evaluated to zero or a negative number.

Fix. Give the window a positive width.

window at (0,0) width 0   # error

W_BATH_VIA_BEDROOM

warning — Bathroom is reachable only through a bedroom.

Cause. Every door path from the entrance to this bathroom/WC passes through a bedroom. That is fine for a private en-suite, but a dwelling's main bathroom should open off circulation (a hall or living space), not a bedroom.

Fix. Add a door connecting the bathroom to a hall/living space, or route circulation so it is not reached only via a bedroom.

door id=d_bath at (5200,4000) width 800 wall partition   # lint: bath only off the bedroom

W_BEDROOM_NO_WINDOW

warning — Bedroom has no window.

Cause. A room labelled as a bedroom has no window on its perimeter (natural light / egress).

Fix. Add a window on an exterior wall of the room.

room at (0,0) size 3000x4000 label "Bedroom"   # lint: no window

W_DOOR_CLEARANCE

warning — Door is narrower than the minimum clear width.

Cause. A door's width is below the configured minimum passable width (default 700 mm).

Fix. Widen the door to at least the minimum clear width.

door at (0,0) width 500 wall exterior   # lint: under 700 mm

W_DOOR_OFF_WALL

warning — Door does not lie on any wall.

Cause. A door's position is not within tolerance of any wall segment, so it has no host.

Fix. Move the door onto a wall, or name its host with wall <id|category>. The diagnostic points at the nearest wall.

door at (9999,9999) width 900   # warning: not on a wall

W_EMPTY_PLAN

warning — Empty plan.

Cause. The plan resolved to no drawable elements.

Fix. Add at least one element (wall, room, …).

plan "Empty" { units mm }   # warning

W_FIXTURE_FLOATING

warning — A plumbing/kitchen fixture is not against a wall.

Cause. A fixture that conventionally needs a wall behind it (WC, basin, shower, sink, counter, stove, fridge…) sits with no wall backing any edge — it appears to float in the middle of the room.

Fix. Move the fixture so one edge is against a wall (supply/waste/venting runs in the wall), or remove it.

furniture wc at (3000,3000) size 400x700   # lint: no wall behind it

W_FIXTURE_WRONG_ROOM

warning — Fixture sits outside its declared room.

Cause. A furniture item declared in <roomId> has its centre outside that room's rectangle, so it is drawn in the wrong space.

Fix. Move the fixture inside the named room, or correct the in <roomId>.

furniture wc at (100,100) size 400x700 in bath   # lint: centre is not inside "bath"

W_FURN_CLEARANCE

warning — A fixture's use-space is blocked.

Cause. The activity clearance directly in front of a fixture (WC, basin, sink, counter, stove…) is intruded by a free-standing piece of furniture, so the fixture can't be used comfortably. Other plumbing/kitchen fixtures are ignored, so a compact bathroom/kitchen run does not trip this.

Fix. Leave the catalogued clearance clear in front of the fixture, or move the obstructing furniture.

furniture stove at (0,0) size 600x600
furniture sofa at (0,650) size 2000x900   # lint: sofa blocks the stove front

W_FURNITURE_OVERLAP

warning — Two pieces of furniture overlap.

Cause. Two furniture/fixture rectangles occupy the same floor area, so they would physically collide — usually a coordinate or size mistake.

Fix. Move or resize one so they no longer intersect; leave a walkway between them.

furniture sofa at (300,300) size 2000x900
furniture bed  at (1000,500) size 1500x2000   # lint: overlaps the sofa

W_HATCH_SCALE

warning — Hatch scale must be positive; using 1.

Cause. A wall material scale evaluated to zero or a negative number.

Fix. Use a positive scale.

wall exterior thickness 200 material brick scale 0 { (0,0) (1,0) }

W_NO_ENTRANCE

warning — The plan has no exterior door.

Cause. The plan has rooms and an exterior wall but no door hosted on an exterior wall, so the building cannot be entered.

Fix. Add a door on an exterior wall.

wall exterior thickness 200 { (0,0) (4000,0) (4000,3000) (0,3000) close }   # lint: no way in

W_OPENING_OFF_WALL

warning — Opening does not lie on any wall.

Cause. A cased opening's position is not within tolerance of any wall segment, so it has no host.

Fix. Move the opening onto a wall, or name its host with wall <id|category>. The diagnostic points at the nearest wall.

opening at (9999,9999) width 1000   # warning: not on a wall

W_ROOM_DISCONNECTED

warning — Room has no door — it can't be entered.

Cause. No door lies on any of the room's walls, so there is no way into the room.

Fix. Add a door on one of the room's walls.

room id=r at (0,0) size 3000x3000   # lint: no door on its perimeter

W_ROOM_NO_FIXTURE

warning — Bathroom or kitchen has no fixtures.

Cause. A room labelled as a bathroom or kitchen contains no plumbing/kitchen fixture (WC, basin, shower, sink, counter…), so it is drawn as an empty box.

Fix. Place the expected fixtures — e.g. import lib/fixtures.arch and add a wc, basin, shower, or kitchen_sink.

room at (4000,4000) size 3000x2000 label "Bath"   # lint: no fixtures inside

W_ROOM_NOT_ENCLOSED

warning — Bathroom is not fully enclosed.

Cause. A run of this bathroom/WC's perimeter is not backed by a wall, so it is open to the adjacent space — a privacy problem for a wet room (a partition that stops short is the usual cause).

Fix. Extend the partition so the room's perimeter is walled on all sides (a door/window in the wall is fine — only a missing wall counts).

wall partition thickness 100 { (4000,0) (4000,4000) }   # lint: stops short, bath left open

W_ROOM_OVERLAP

warning — Rooms overlap.

Cause. Two room rectangles intersect.

Fix. Adjust positions/sizes if the overlap is unintended (it is allowed).

room at (0,0) size 2000x2000
room at (1000,0) size 2000x2000   # warning

W_ROOM_TOO_SMALL

warning — Room is implausibly small.

Cause. A room's floor area is below the configured minimum (default 4 m²).

Fix. Increase its size, or merge it into an adjacent space.

room at (0,0) size 1000x1000 label "Closet"   # lint: 1 m²

W_ROOM_UNREACHABLE

warning — Room cannot be reached from the entrance.

Cause. The building has an entrance, but this room has no door/opening path back to the exterior — it is sealed off from the circulation.

Fix. Add a door or cased opening linking it (directly or through a hall) to a space that reaches the entrance.

room at (5000,0) size 3000x3000 label "Store"   # lint: no path from the entrance

W_SANITIZED_CONFIG

warning — A disallowed config value was stripped.

Cause. A theme/style value contained markup or a data: URL and was blanked for safety.

Fix. Use a plain colour/string value (no <, >, or url(data:…)).

theme { wall: "<script>" }   # warning: stripped

W_SWING_OBSTRUCTED

warning — Door swing is obstructed.

Cause. The quarter-circle a door leaf sweeps overlaps a piece of furniture/fixture or another door's swing, so the door cannot open fully.

Fix. Move the door or the obstruction, flip the hinge/swing, or use a sliding door so the leaf clears.

door at (4000,1500) width 900 swing in   # lint: leaf sweeps onto the bed

W_UNKNOWN_MATERIAL

warning — Unknown wall material; using the default hatch.

Cause. A wall material name is not one of the known hatches.

Fix. Use a known material (e.g. brick, concrete, insulation, tile) or omit it.

wall exterior thickness 200 material marble { (0,0) (1,0) }   # warning

W_UNKNOWN_STYLE_KEY

warning — Unknown style key.

Cause. A style <kind> { … } block uses a key not valid for that element kind.

Fix. Use a valid key (e.g. fill / stroke / label, depending on the kind).

style room { nope: "#000" }   # warning

W_UNKNOWN_THEME_KEY

warning — Unknown theme key.

Cause. A theme { … } block uses a key that is not a theme property or alias.

Fix. Use a known theme key (see the language reference / hover).

theme { nope: "#000" }   # warning

W_WINDOW_OFF_WALL

warning — Window does not lie on any wall.

Cause. A window's position is not within tolerance of any wall segment, so it has no host.

Fix. Move the window onto a wall, or name its host with wall <id|category>. The diagnostic points at the nearest wall.

window at (9999,9999) width 1200   # warning: not on a wall