yoshida yoshida
Open the editor

Docs Format

Diagnostics

On this page

Every problem yoshida finds is a diagnostic with a severity, a stable numeric code, a place and a message. Loading and checking report all problems, not just the first, and rendering starts only when there are zero errors.

SeverityMeaning
errorThe project cannot be rendered. Fix it
warningRendering works but something is probably wrong (a text was cut, a font is missing)
hintInformation only

Codes are stable and never reused. The first digit groups them: 1xxx file and format, 2xxx card data, 3xxx expressions and layout, 4xxx assets, 5xxx limits.

Reading a message

On the command line:

designs/tour.design.json:41:17: error[3002]: unknown name 'levl'
  at /layers/4/repeat/count (expression bytes 0..4)
  hint: did you mean 'level'?

file:line:column, severity and code, the message (with card <id>: in front when it belongs to one card), the JSON pointer of the field, the byte range inside an expression when there is one, and a hint. Hints such as did you mean 'color'? come from a closest-name search over the valid names.

Habits from other languages

Some operators and forms from other languages are not in yoshida. The error says what to write instead:

You writeErrorHint
&, &&3001 unexpected '&'use 'and'
|, ||3001 unexpected '|'use 'or'
!3001 unexpected '!'use 'not'
^, **3001 unexpected '^' or '**'use pow(a, b)
=3001 unexpected '='use '==' to compare
<>3001 unexpected '<>'use '!=' for not equal
1e33001 unknown unit after a numberexponent notation is not supported; write 1000
.53001 unexpected '.'write 0.5
7%33001put spaces around % for the remainder: 7 % 3
'a' + b3003 'needs numbers'join text with a template, e.g. "{a} {b}"

JSON shape

yoshida check --format json, yoshida render --format json, the server's 422 response and the WebAssembly module all use this object per diagnostic:

{
  "severity": "error",
  "code": 3002,
  "file": "designs/tour.design.json",
  "path": "/layers/4/repeat/count",
  "line": 41,
  "col": 17,
  "span": [0, 4],
  "message": "unknown name 'levl'",
  "hint": "did you mean 'level'?",
  "card": null
}
FieldMeaning
severityerror, warning or hint
codeNumber from the table below
fileProject path of the file; empty for project-wide problems
pathJSON Pointer to the field (/layers/3/box/x; inside groups /layers/2/layers/0/box/x)
line, col1-based position in the file (0 when unknown)
span[start, end] byte range inside the expression string, or [0, 0]
messageWhat is wrong
hintWhat to try, or null
cardThe card id for render-time problems, or null

In the editor

The Problems panel collects them, groups identical problems from many cards into one block and jumps to the field, the card or the line when you click.

Codes

1xxx: files and format

CodeSeverityMeaning
1001errorJSON syntax error
1101errorUnknown field
1102errorMissing required field (also: a CSV file that no set uses is a warning with this code)
1103errorWrong JSON type for the field's kind, or a word that is not one of an enum's options
1104errorformat missing
1105errorUnsupported format version
1106errorParam, constant or function name is invalid, is a reserved word, or collides with another param, constant or function name
1107errorParam has neither default nor required
1108errorDuplicate or invalid layer id
1109errorPolygon has fewer than 3 points (2 for an open polygon)
1110errorImage w and h both auto
1111errorrepeat needs exactly one of count / each; a polygon needs exactly one of points / shape
1112errorextends across different layer types (including a group), or of a divider
1113warningA design function has the name of a built-in function; the design's function is used in this design instead of the built-in
1114warningA rect, ellipse or closed polygon has a stroke but no fill (and no gradient), so it is filled opaque white. Add "fill": "#00000000" for an outline, or a color to fill it on purpose. Not reported for an open polygon or an arc with "pie": false, which have no fill
1201errorFile not found
1202errorCSV syntax error (also a missing header row, or a row with the wrong number of fields)
1203errorPath escapes the project root

2xxx: card data

CodeSeverityMeaning
2001warningCard sets an unknown param
2002errorValue outside min / max / max_length
2003errorRequired param missing
2004errorDuplicate card id
2005errorCard id not safe as a file name
2006errorCard value has the wrong type, or is not an enum option

3xxx: expressions and layout

CodeSeverityMeaning
3001errorExpression syntax error
3002errorUnknown name or function
3003errorType mismatch or wrong function arguments
3004errorReference or extends cycle (also: an iteration reading a later one, a group's translate reading a layer inside it)
3005errorReference to a repeated layer without an iteration index, or into nested repeats
3006errorUnit not valid in this field
3101errorNegative width or height (at render time)
3102errorList index or iteration index out of range, or last() of an empty list (at render time)
3103errorMath error (division by zero, empty list average/min/max, result not a finite number, value outside a function's domain) (at render time)
3104errorList lookup by a key no item has (at render time)
3105errorText is not a valid date, time or date-time, or a date token is used on a time-only value (at render time)
3106errorText result over 10 000 bytes (at render time)
3107errorArgument out of range: roman outside 1 to 3999, an empty part separator, rand_int with lo greater than hi (at render time)
3108errorQR code text too long for its error correction level (at render time)
3109errorAn anchor, align or fit expression gives a word that is not one of the options, or a baseline anchor on a layer that is not text (at render time)
3201warningText truncated by max_lines
3202hintLayer entirely outside the canvas
3203warningText does not fit max_width / max_height even at min_size
3204warningA module of a QR code is smaller than one pixel
3205warningA QR code has little contrast against its fill, or is lighter than it
3207warningA QR code with logo is not at level high, or the cleared middle covers more than 20 %
3208warningA module of a QR code prints narrower than 0.5 mm at the canvas dpi
3209warningText with markup uses an icon the design does not know (left out), or <i> without font_italic (drawn upright)

4xxx: assets

CodeSeverityMeaning
4001errorImage not found or unreachable (placeholder in preview)
4002errorImage could not be decoded
4003warningNeither the font nor the bundled fallback fonts have glyphs for some characters (drawn as boxes)
4004errorFont name not declared in fonts
4005warningFont file missing or not a TrueType/OpenType font; the default font is used

5xxx: limits

CodeSeverityMeaning
5001errorA limit was exceeded: canvas size, layers after repeat (the message names the layers that use most of it), repeat iterations, group nesting, cards per set, image size. Most can be raised. See Limits and Versioning

Common fixes

You seeUsually meansTry
1101 unknown field 'colour'A typoUse the hint: color
1107A param with no defaultAdd "default" or "required": true
1108Two layers with the same id, maybe in different groupsRename one (the editor updates references)
3002 unknown nameTypo in a param or @layerCheck Names and references
3003 in a textA list or item inside {...}Use a field or an index
3005Referencing a layer that uses repeatPick an iteration, @layer[0].bounds.cx, or reference a group around it
5001 ... visible layers after repeatA card draws more layers than the limit (500 by default)Hide variants with visible, see the layer limit, or raise the limit with YOSHIDA_MAX_LAYERS
3006% in size, radius, ...Use vw or vh
3104stats.Speed on a card without that keyAdd the item, or check spelling and case; get(stats, 'Speed', 0) gives a fallback
3103 from avg, min or maxAn empty listGuard with len(list) > 0, or give a fallback in the expression
3105A date that is not YYYY-MM-DDUse the ISO form; see Dates and times
1113A design function named like a built-inRename the function, or keep the name on purpose: the design's function is used in this design
4001Image path wrong, URL unreachableFix the path; with --preview you get a placeholder
4005Font file missingAdd the file, or fix the fonts path

↑↓ to moveEnter to openEsc to close