SPB Git

Repository Public

errors.md 21.9 KB 652 lines markdown

1# Error Handling23ORIX Script reports problems at two moments.45- **Before the script runs**, the compiler checks everything it can. One error is enough to refuse the whole script: nothing is executed.6- **While the script runs**, a few things can still go wrong because they depend on the state of the rig. A run-time error cancels the automation; the audio is not affected.78Every message has a stable code in square brackets. This chapter explains every code.910## Reading a message1112In the editor and in the command-line checker a diagnostic looks like this:1314```text154:5: error: Unknown deck parameter 'volum' in 'deck.A.volum'. Did you mean 'volume'? [E-PATH]16```1718`4:5` is the line and the column. `error` or `warning` is the severity. Codes starting with `E-` are errors; codes starting with `W-` are warnings, which do not prevent the script from running.1920In the console and the live log a run-time error is shown with its line:2122```text23line 7: Deck C has no track loaded. [E-ACTION]24```2526The compiler keeps going after an error and reports several at once. Fix the first one first: later messages are sometimes consequences of it.2728## What happens on a run-time error29301. Every task, ramp and event handler of the automation is cancelled.312. Every effect that the automation switched on and had not switched off again is switched off, whether it was switched on with `enable()`, with `toggle()` or by writing `enabled = true`. The log shows `bypassed fx.echo after the failure` for each.323. The automation's state becomes "failed" and the error is logged with its line and code.3334Other automations keep running. Decks keep playing. Controls other than those effects stay where the script left them: a fader that was halfway through a ramp stays halfway. There is no way to catch an error inside a script; prevent it with a condition instead (`if deck.B.loaded { … }`).3536## Errors found by the compiler3738### E-SYNTAX3940The text does not follow the grammar.4142Typical causes: a missing brace or parenthesis, a missing value after `=`, a statement outside an automation, a reserved word used as the name of a variable, a `for` loop variable or a function parameter, `else` without `if`, a function name used without parentheses, an empty automation name.4344```orixdj-error45deck.A.volume =46wait 4 beats47```4849```text50Expected a value, found end of line. [E-SYNTAX]51```5253Fix: read the message; it names what was expected and what was found. Check the line above as well when the message points at the start of a line.5455### E-LEX5657A character or a piece of text cannot be read at all.5859Typical causes: a character that is not part of the language (`#`, `@`, `$`), a string without its closing quote, a `/*` comment that is never closed.6061```orixdj-error62deck.A.volume = -6dB # quieter63```6465```text66Unexpected character '#'. [E-LEX]67```6869Fix: comments start with `//`. Strings start and end with `"` on the same line.7071### E-UNIT7273A number is followed by letters that are not a unit.7475```orixdj-error76deck.A.filter.highpass = 2khz77```7879```text80Unknown unit 'khz'. Units: Hz, kHz, dB, beat(s), bar(s), s, ms, min, bpm, st, %. [E-UNIT]81```8283Fix: units are case-sensitive: `kHz`, `Hz`, `dB`, `ms`. See [Units](units.md).8485### E-EMPTY8687The script contains no automation.8889```orixdj-error90// This file should contain at least one: automation "Name" { … }91fn half(x: number) -> number {92    return x / 293}94```9596```text97The script defines no automation. Start with: automation "Name" { … } [E-EMPTY]98```99100Fix: wrap the statements in `automation "Name" { … }`.101102### E-TYPE103104A value has the wrong type for where it is used.105106Typical causes: a missing unit (`wait 4`, `deck.A.filter.highpass = 500`), the wrong unit (`deck.A.volume = 20Hz`), arithmetic between different kinds (`-6dB + 3`), a condition that is not true/false (`if deck.A.bpm { … }`), assigning a different type to a variable, using an action as a value (`let v = deck.A.play()`), array elements of different types, a wrong argument type in a call.107108```orixdj-error109wait 4110```111112```text113'wait' needs a duration such as 4beats, 2bars or 500ms, not number. [E-TYPE]114```115116Fix: add or correct the unit. The message says which type is expected and often suggests the form to write. See [Types](types.md).117118### E-RANGE119120A constant value is outside what is accepted.121122Typical causes: a value beyond the range of a parameter (`deck.A.volume = 6dB`, `mixer.crossfader = 1.5`, `fx.delay.feedback = 2`), a text that is not one of the accepted ones (`mixer.curve = "wobbly"`), a negative wait, an `over` of zero length, `at bar 0`, a hot cue outside 1…8, a trigger outside 1…16, a loop length outside 1/64…256 beats, a loop count that is negative or not whole, an array index outside the array, a linear level outside 0…4.123124```orixdj-error125mixer.crossfader = 1.5126```127128```text1291.5 is outside the range of 'mixer.crossfader' (0 … 1). [E-RANGE]130```131132Fix: use a value in the range. The ranges are listed in the reference chapters and by `help <path>` in the console.133134At run time, a computed value outside the range of a parameter is not an error: it is limited to the range and counted as a clamped value. `E-RANGE` at run time is raised for things that cannot be limited sensibly: an array index outside the array, a loop count that is not a whole number, a trigger number outside 1…16, a negative duration, a bar or beat number below 1.135136```orixdj-error137let pattern = [1, 2, 3]138var index = 2139index = index + 1140print(pattern[index])141```142143```text144Index 3 is outside the array (0 to 2). [E-RANGE]145```146147### E-PATH148149A path does not exist, or is used the wrong way.150151Typical causes: a misspelt parameter or action (`deck.A.volumee`, `deck.A.plya()`), an action written without parentheses or assigned to (`deck.A.play = true`), a parameter called like an action (`deck.A.volume()`), an incomplete path (`fx.delay = 1`, `deck.A = 1`), an action on `mixer` or `master`, which have none.152153```orixdj-error154deck.A.plya()155```156157```text158Unknown deck action 'plya'. Did you mean 'play'? [E-PATH]159```160161Fix: follow the suggestion, or look the path up in [Deck Commands](deck-api.md), [Mixer Commands](mixer-api.md) or [Effects Commands](effects-api.md). The editor's autocomplete lists the valid continuations of a path.162163### E-DECK164165The deck letter does not exist.166167```orixdj-error168deck.E.play()169```170171```text172Unknown deck 'E'. Decks are A, B, C and D. [E-DECK]173```174175Fix: decks are `A`, `B`, `C` and `D`, in capitals.176177### E-EFFECT178179The effect name does not exist.180181```orixdj-error182fx.warp.enable()183```184185```text186Unknown effect 'warp'. Effects: reverb, delay, echo, flanger, phaser, chorus, distortion, bitcrusher, highpass, lowpass, bandpass, tremolo, autopan, gate, compressor, limiter, beatrepeat, noise. [E-EFFECT]187```188189Fix: use one of the listed names. See [Effects Commands](effects-api.md).190191### E-CAPABILITY192193The script uses a deck or an effect that the setup running it does not provide. The compiler is told how many decks and which effects are available; a script written for four decks is refused, before it runs, on a setup that offers two.194195```text196Deck C is not available: this setup has 2 decks. [E-CAPABILITY]197The effect 'reverb' is not available in this setup. [E-CAPABILITY]198```199200Fix: use only the decks and effects of the setup. The standard configuration of ORIX DJ provides four decks and every effect, so this code does not appear there.201202### E-READONLY203204The script tries to set something that can only be read.205206```orixdj-error207deck.A.position = 30s208```209210```text211'deck.A.position' is read-only. [E-READONLY]212```213214Fix: properties such as `position`, `remaining`, `playing`, `loaded`, `level`, `master.beat` describe the state; change the state with an action. To move the playhead use `deck.A.seek(30s)`.215216### E-RAMP217218A ramp (`->`) is used where it cannot be.219220Two causes:221222- `->` outside an `over` block;223- ramping a control that cannot be ramped: a switch, a text or a duration.224225```orixdj-error226over 4 beats { deck.A.keylock -> true }227```228229```text230'deck.A.keylock' (bool) cannot be ramped; set it with '='. [E-RAMP]231```232233Fix: put the ramp inside `over duration { … }`, or set the control with `=`. Controls marked "read, write, ramp" in the reference can be ramped. See [Timing](timing.md).234235### E-OVER236237A statement is not allowed inside an `over` block. Only ramps, assignments, action calls, declarations and `print` are.238239```orixdj-error240over 4 beats {241    deck.A.volume -> -12dB242    wait 1 beat243}244```245246```text247Only ramps ('->'), assignments and actions are allowed inside 'over'. Move this statement outside the block. [E-OVER]248```249250Fix: move the statement before or after the block. To do something during a ramp, schedule it with `at` before the `over`.251252### E-CURVE253254The curve name after `curve` is not one of `linear`, `easeIn`, `easeOut`, `smooth`, `exp`.255256```orixdj-error257over 4 beats curve wavy { mixer.crossfader -> 1 }258```259260```text261Unknown curve 'wavy'. Curves: linear, easeIn, easeOut, smooth, exp. [E-CURVE]262```263264### E-UNDECLARED265266A name is used that has not been declared.267268Typical causes: assigning to a variable without `let` or `var`, a misspelt variable, using a variable outside the block where it was declared, calling a function that does not exist.269270```orixdj-error271tempo = master.bpm272```273274```text275'tempo' is not declared. Declare it first: let tempo = …  (or 'var' if it changes). [E-UNDECLARED]276```277278Fix: declare it (`let tempo = master.bpm`), or correct the spelling. See [Variables](variables.md).279280### E-CONST281282Something that cannot change is assigned, or a top-level constant is not constant.283284Causes: assigning to a `let` variable, to a function parameter, to a loop variable or to a top-level constant; a top-level `let` whose value reads the rig.285286```orixdj-error287let count = 0288count = count + 1289```290291```text292'count' was declared with 'let' and cannot change. Declare it with 'var'. [E-CONST]293```294295Fix: declare the variable with `var`. Move a top-level `let` that reads live values into the automation.296297### E-REDECLARED298299A name is defined twice.300301Causes: two variables with the same name in the same block, two parameters with the same name, two top-level constants, two functions, a function named like a builtin or a reserved word, two automations with the same name in one file.302303```orixdj-error304let fade = 4 bars305let fade = 8 bars306```307308```text309'fade' is already declared in this block. [E-REDECLARED]310```311312Fix: rename one of them, or use `var` and assign.313314### E-UNBOUNDED315316A `while` loop has no valid bound, or reached it.317318At compile time: `limit` is missing, or is not a constant whole number from 1 to 10000.319320```orixdj-error321while deck.A.playing {322    wait 1 beat323}324```325326```text327A 'while' loop needs an iteration bound: while condition limit 64 { … }. [E-UNBOUNDED]328```329330At run time: the loop made `limit` turns and its condition was still true.331332```text333The 'while' loop reached its limit without its condition becoming false. [E-UNBOUNDED]334```335336Fix: add `limit N`. If giving up after N turns is expected, count the turns in the condition. See [Loops](loops.md).337338### E-LIMIT339340A fixed limit of the language or of the runtime is exceeded.341342At compile time: a script larger than 256 KB, more than 20000 statements, blocks or expressions nested more than 20 deep, a loop of more than 10000 turns, an `every` period shorter than 1/64 beat, an array of more than 256 elements, more than 32 event handlers, more than 512 variables in one automation or function, a string literal longer than 512 characters, a duration above 100000 beats.343344```orixdj-error345repeat 1000000 {346    wait 1 beat347}348```349350```text351A loop cannot run more than 10000 times. [E-LIMIT]352```353354At run time: the same loop and duration limits when the values are computed, more than 256 scheduled blocks pending, more than 128 ramps at once, function calls nested more than 16 deep, a string longer than 2048 characters built with `+`.355356Fix: restructure. These limits are far above what a performance script needs; reaching one usually reveals a mistake such as a loop count in the wrong unit. All the values are in [Performance Guidelines](performance.md).357358### E-RECURSION359360A function calls itself, directly or through other functions.361362```text363Function 'countdown' calls itself, directly or through other functions. Recursion is not allowed: automations must be bounded. [E-RECURSION]364```365366Fix: use a loop. See [Functions](functions.md).367368### E-PURE369370A function that returns a value does something other than compute.371372Causes, inside a `fn … -> type`: `wait`, `at`, `over`, `every`, `on`; setting a control or calling an action; reading a live value; `print`; `random()`; `stop`; calling a procedure.373374```orixdj-error375fn slow(x: number) -> number {376    wait 1 beat377    return x378}379380automation "X" {381    print(slow(1))382}383```384385```text386'wait' is not allowed in a function that returns a value. Use a function without a return type for timed procedures. [E-PURE]387```388389Fix: remove the return type to make it a procedure, or pass live values in as arguments.390391### E-RETURN392393`return` is misused, or a value function may end without returning.394395Causes: `return` in an automation (use `stop`), `return value` in a procedure, `return` without a value in a value function, a value function with a path that reaches its end without `return`.396397```orixdj-error398if not deck.B.loaded {399    return400}401```402403```text404'return' is only valid inside a function. Use 'stop' to end the automation. [E-RETURN]405```406407### E-ARGS408409A call has the wrong number of arguments, or a builtin is given arguments it does not accept.410411```orixdj-error412deck.A.seek()413```414415```text416seek(position: duration) takes 1 argument, not 0. [E-ARGS]417```418419```orixdj-error420let lowest = min(1, 2dB)421```422423```text424min() expects two values of the same numeric type. Signature: min(a, b) -> same type [E-ARGS]425```426427Fix: check the signature in the reference, or with `help deck.A.seek` in the console.428429### E-EVENT430431An event handler is wrong.432433Causes: an event that does not exist (`on deck.A.finished`), `on trigger` without a number, `on` inside a loop, `on` inside a function.434435```orixdj-error436on trigger { deck.A.play() }437```438439```text440'on trigger' needs a trigger number: on trigger(1) { … }. [E-EVENT]441```442443Fix: the events are `beat`, `bar`, `trigger(n)` and `deck.X.trackEnd`, `play`, `pause`, `loaded`, `beat`. Declare handlers in the automation, outside loops. See [Events](events.md).444445### E-LOOP446447`break` or `continue` is used outside a loop.448449```orixdj-error450if deck.A.playing {451    break452}453```454455```text456'break' is only valid inside a loop. [E-LOOP]457```458459Fix: use `stop` to end the automation, or `return` to leave a procedure. A block scheduled with `at` inside a loop is not part of the loop.460461### E-MATH462463A calculation has no finite result, usually a division by zero.464465```orixdj-error466let ratio = 1 / 0467```468469```text470The result of '/' is not a finite number (division by zero?). [E-MATH]471```472473The compiler finds it when the operands are constants; otherwise it is a run-time error. Fix: test the divisor first.474475```orixdj476let tempo = deck.B.trackBpm477if tempo > 0 {478    print(deck.A.bpm / tempo)479} else {480    print("deck B has no tempo")481}482```483484## Errors that only occur while running485486### E-ACTION487488An action could not be performed in the current state of the rig. The message comes from the engine and says why.489490| Message | Cause |491| --- | --- |492| `Deck C has no track loaded.` | `play()`, `cue()`, `seek()`, `jump()`, `loop()` or `hotcue()` on an empty deck |493| `Deck A: hot cue 3 is not set.` | `hotcue(3)` before any `setHotcue(3)` |494| `Deck A has no previous loop.` | `reloop()` when no loop was ever set |495| `Deck A: set a loop start first.` | `loopOut()` without `loopIn()` |496| `Deck A: the loop end must be after the loop start.` | `loopOut()` at or before the loop start |497| `The loop does not fit before the end of the track.` | `loop()` too close to the end |498| `Deck A is playing; pause it before loading.` | `load()` or `loadNext()` on a playing deck |499| `Deck A is playing; pause it before ejecting.` | `eject()` on a playing deck |500| `Deck A has no beat grid; seek with seconds instead.` | `seek(32 beats)` on a track without analysis |501| `The rack is full (8 effects).` | `enable()` of a ninth effect in one rack |502| `No library track matches "…".` | `load("…")` with a title that is not in the library |503504```orixdj-error505deck.A.hotcue(3)506```507508```text509Deck A: hot cue 3 is not set. [E-ACTION]510```511512Fix: test the state before acting.513514```orixdj515if deck.C.loaded {516    deck.C.play()517} else {518    print("deck C is empty")519}520```521522### E-BUDGET523524The script did too much work without letting time pass: more than 20000 operations in one scheduler step, or more than 5000000 over the life of the automation. An operation is roughly one statement, one loop turn, one arithmetic or comparison operator, or one read of a live value.525526```orixdj-error527var n = 0528repeat 10000 {529    n = n + 1530}531```532533```text534More than 20000 operations without a wait. Add a 'wait' inside the loop or reduce its work. [E-BUDGET]535```536537Fix: put a `wait` in the loop, or reduce the number of turns. See [Performance Guidelines](performance.md).538539### E-RATE540541The script issued more than 512 parameter changes and actions within one beat. Ramps are not counted.542543```orixdj-error544repeat 2000 {545    mixer.crossfader = 0.5546}547```548549```text550More than 512 commands in one beat. The automation was stopped to protect the performance. [E-RATE]551```552553Fix: a loop that writes controls needs a `wait` in its body. For smooth movement use `over` instead of many small steps.554555### E-UNAVAILABLE556557The script reads a value, or starts a ramp from a value, that the rig cannot provide at that moment.558559```text560'fx.echo.mix' cannot be read right now (the effect is not in the rack; call enable() first). [E-UNAVAILABLE]561```562563In the current engine and in the simulator, every path of the reference can always be read: an effect that is not in a rack reads as its default values. This code is therefore not expected in normal use. If you do see it, the fix suggested by the message applies: call `enable()` on the effect (or set one of its parameters) before reading or ramping it.564565### E-INTERNAL566567The runtime met a condition it did not expect. This indicates a defect in ORIX DJ, not in your script. The automation is cancelled like for any run-time error. Keep the script and report it.568569## Warnings570571Warnings do not stop a script from running. They point at things that are legal but probably not what you meant.572573| Code | Message | Meaning and fix |574| --- | --- | --- |575| `W-UNREACHABLE` | This statement is never reached. | The statement follows `stop`, `break`, `continue` or `return` in the same block. Remove it or move it up. |576| `W-UNUSED` | The result of 'name' is not used. | A value function or builtin is called as a statement and its result is thrown away. Assign it with `let`, or remove the call. |577| `W-SHADOW` | 'name' hides the top-level constant of the same name. | A variable in an automation or function has the name of a file constant. Rename one of them. |578| `W-OVER` | This 'over' block ramps nothing; it only waits. Use 'wait' if that is intended. | The block contains no `->`. Often an `=` was typed instead of `->`. |579| `W-RAMP` | 'path' is ramped twice in the same block; the last ramp wins. | Remove one of the two ramps. |580| `W-AT` | 'at bar' inside a function counts from the start of the automation, not from the call. | Use `wait` inside functions, or accept the meaning. |581582```orixdj583automation "Warnings" {584    over 1 bar {585        deck.A.volume = -6dB        // W-OVER: no ramp in this block586    }587    deck.A.volume = 0dB588    stop589    deck.A.pause()                  // W-UNREACHABLE590}591```592593Two more warnings are produced while running and appear in the log, without a code:594595```text596line 9: 'at' names a position 4 beats in the past; running it now597line 12: 'wait until' names a position that has already passed598```599600## Writing scripts that do not fail601602- Check before acting: `if deck.B.loaded`, `if deck.B.trackBpm > 0`, `if not deck.B.playing`.603- Print the reason and `stop` when the situation is wrong.604- Switch effects on from the script that uses them: if it fails, the effects it switched on are switched off.605- Run every new script in the simulator, with the decks in the state you expect on stage and in a state you do not expect (deck B empty, deck A paused).606- Keep `panic` within reach.607608## Code index609610| Code | When | In one line |611| --- | --- | --- |612| E-SYNTAX | compile | The text does not follow the grammar |613| E-LEX | compile | Unreadable character, unterminated string or comment |614| E-UNIT | compile | Unknown unit after a number |615| E-EMPTY | compile | No automation in the script |616| E-TYPE | compile, run | Wrong type or unit |617| E-RANGE | compile, run | Constant outside its range; bad index, count or position |618| E-PATH | compile | Unknown or misused path |619| E-DECK | compile | Unknown deck letter |620| E-EFFECT | compile | Unknown effect |621| E-CAPABILITY | compile | Deck or effect not available in this setup |622| E-READONLY | compile | Writing a read-only property |623| E-RAMP | compile, run | `->` outside `over`, or on a control that cannot be ramped |624| E-OVER | compile, run | Statement not allowed inside `over` |625| E-CURVE | compile | Unknown ramp curve |626| E-UNDECLARED | compile | Unknown variable or function |627| E-CONST | compile | Assigning to something constant |628| E-REDECLARED | compile | Name defined twice |629| E-UNBOUNDED | compile, run | `while` without a valid limit, or limit reached |630| E-LIMIT | compile, run | A fixed limit exceeded |631| E-RECURSION | compile | A function calls itself |632| E-PURE | compile, run | Side effect or timing in a value function |633| E-RETURN | compile, run | Misplaced or missing `return` |634| E-ARGS | compile | Wrong number or kind of arguments |635| E-EVENT | compile | Invalid event handler |636| E-LOOP | compile | `break` or `continue` outside a loop |637| E-MATH | compile, run | Non-finite result |638| E-ACTION | run | The rig refused an action |639| E-BUDGET | run | Too many operations without a wait |640| E-RATE | run | Too many commands in one beat |641| E-UNAVAILABLE | run | A value cannot be read |642| E-INTERNAL | run | Defect in the runtime |643644## Related645646- [Troubleshooting](troubleshooting.md)647- [Debugging](debugger.md)648- [Types](types.md)649- [Performance Guidelines](performance.md)650- [Automation Scheduling](scheduling.md)651- [Language Syntax](syntax.md)652
Files main
Menu

Theme