Diagnostics and limits
Stack diagnostics are structured results, not console prose. They have a stable code, error or warning severity, a one-based end-exclusive source range, a concise message, and an ordered expected list. Corrective help and related source ranges are included when useful.
Processing and severity
Tools process encoding and tokens, grammar, identifiers and defaults, semantic limits, theme and icon resolution, layout, then rendering. Errors in the first four stages prevent rendering. Theme, icon, density, and layout-hint warnings can accompany a fallback SVG.
The Playground clears stale diagnostics after source edits. Selecting a result focuses its primary source; related information can point back to an earlier declaration.
Complexity limits
| Item | Draft Stack 1.0 limit |
|---|---|
| Diagrams per document | 1 |
| Nodes | 1 to 40 |
| Groups | 0 to 12 |
| Group nesting below diagram | 3 levels |
| Edges | 0 to the smaller of 80 or twice the node count |
| Node degree before warning | 12 incident edge declarations |
Exceeding a hard limit is STK4003. A node above the recommended degree remains valid but emits STK4002. Split large systems into focused diagrams rather than compressing an exhaustive graph.
Portable diagnostic codes
| Code | Severity | Meaning |
|---|---|---|
STK1001 | Error | Input is not valid UTF-8 |
STK1002 | Error | A byte order mark is present |
STK1003 | Error | A string has an invalid escape or decoded value |
STK2001 | Error | The declared language version is unsupported |
STK2002 | Error | An unexpected token, declaration, property, value, or operator was found |
STK2003 | Error | Input ended before the current construct was complete |
STK3001 | Error | An identifier is invalid |
STK3002 | Error | An identifier is declared more than once |
STK3003 | Error | An edge references an unknown node |
STK3004 | Error | A group is used as an edge endpoint |
STK3005 | Error | An edge connects a node to itself |
STK3006 | Error | An exact duplicate edge is declared |
STK3007 | Error | A property occurs more than once in one block |
STK3008 | Error | A title, label, or detail violates its text constraints |
STK3009 | Error | A group has no descendant node |
STK3010 | Error | Group nesting exceeds the language limit |
STK3011 | Error | A layout reference is invalid in its scope |
STK3012 | Error | A layout block or singleton layout statement is duplicated |
STK3013 | Error | An icon identifier is malformed |
STK3014 | Error | A diagram contains more than one theme statement |
STK4001 | Warning | An order hint could not be satisfied |
STK4002 | Warning | A node exceeds the recommended incident-edge degree |
STK4003 | Error | A diagram exceeds a language complexity limit |
STK5001 | Warning | An icon is unavailable in the effective theme; its kind fallback was used |
STK6001 | Warning | A requested non-core theme is unavailable; default was used |
Code families reserve STK1000 for encoding and lexical errors, STK2000 for syntax, STK3000 for names and semantics, STK4000 for layout and complexity, STK5000 for icons, and STK6000 for themes. STK9000 is for implementation failures, never a source mistake. Implementations may add diagnostics only under their own non-STK prefix.
Recovery rules
A parser may recover to report independent errors together, but it cannot render a partial diagram as valid. Unknown declarations, properties, enum values, and operators are never ignored. This avoids successful-looking output that silently lost authored meaning.