SPB Git

Repository Public

errors.md 21.9 KB

# Error Handling

ORIX Script reports problems at two moments.

  • Before the script runs, the compiler checks everything it can. One error is enough to refuse the whole script: nothing is executed.
  • 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.

Every message has a stable code in square brackets. This chapter explains every code.

# Reading a message

In the editor and in the command-line checker a diagnostic looks like this:

text
4:5: error: Unknown deck parameter 'volum' in 'deck.A.volum'. Did you mean 'volume'? [E-PATH]

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.

In the console and the live log a run-time error is shown with its line:

text
line 7: Deck C has no track loaded. [E-ACTION]

The compiler keeps going after an error and reports several at once. Fix the first one first: later messages are sometimes consequences of it.

# What happens on a run-time error

  1. Every task, ramp and event handler of the automation is cancelled.
  2. 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.
  3. The automation's state becomes "failed" and the error is logged with its line and code.

Other 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 { … }).

# Errors found by the compiler

# E-SYNTAX

The text does not follow the grammar.

Typical 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.

orixdj-error
deck.A.volume =
wait 4 beats
text
Expected a value, found end of line. [E-SYNTAX]

Fix: 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.

# E-LEX

A character or a piece of text cannot be read at all.

Typical causes: a character that is not part of the language (#, @, $), a string without its closing quote, a /* comment that is never closed.

orixdj-error
deck.A.volume = -6dB # quieter
text
Unexpected character '#'. [E-LEX]

Fix: comments start with //. Strings start and end with " on the same line.

# E-UNIT

A number is followed by letters that are not a unit.

orixdj-error
deck.A.filter.highpass = 2khz
text
Unknown unit 'khz'. Units: Hz, kHz, dB, beat(s), bar(s), s, ms, min, bpm, st, %. [E-UNIT]

Fix: units are case-sensitive: kHz, Hz, dB, ms. See Units.

# E-EMPTY

The script contains no automation.

orixdj-error
// This file should contain at least one: automation "Name" { … }
fn half(x: number) -> number {
    return x / 2
}
text
The script defines no automation. Start with: automation "Name" { … } [E-EMPTY]

Fix: wrap the statements in automation "Name" { … }.

# E-TYPE

A value has the wrong type for where it is used.

Typical 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.

orixdj-error
wait 4
text
'wait' needs a duration such as 4beats, 2bars or 500ms, not number. [E-TYPE]

Fix: add or correct the unit. The message says which type is expected and often suggests the form to write. See Types.

# E-RANGE

A constant value is outside what is accepted.

Typical 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.

orixdj-error
mixer.crossfader = 1.5
text
1.5 is outside the range of 'mixer.crossfader' (0 … 1). [E-RANGE]

Fix: use a value in the range. The ranges are listed in the reference chapters and by help <path> in the console.

At 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.

orixdj-error
let pattern = [1, 2, 3]
var index = 2
index = index + 1
print(pattern[index])
text
Index 3 is outside the array (0 to 2). [E-RANGE]

# E-PATH

A path does not exist, or is used the wrong way.

Typical 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.

orixdj-error
deck.A.plya()
text
Unknown deck action 'plya'. Did you mean 'play'? [E-PATH]

Fix: follow the suggestion, or look the path up in Deck Commands, Mixer Commands or Effects Commands. The editor's autocomplete lists the valid continuations of a path.

# E-DECK

The deck letter does not exist.

orixdj-error
deck.E.play()
text
Unknown deck 'E'. Decks are A, B, C and D. [E-DECK]

Fix: decks are A, B, C and D, in capitals.

# E-EFFECT

The effect name does not exist.

orixdj-error
fx.warp.enable()
text
Unknown effect 'warp'. Effects: reverb, delay, echo, flanger, phaser, chorus, distortion, bitcrusher, highpass, lowpass, bandpass, tremolo, autopan, gate, compressor, limiter, beatrepeat, noise. [E-EFFECT]

Fix: use one of the listed names. See Effects Commands.

# E-CAPABILITY

The 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.

text
Deck C is not available: this setup has 2 decks. [E-CAPABILITY]
The effect 'reverb' is not available in this setup. [E-CAPABILITY]

Fix: 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.

# E-READONLY

The script tries to set something that can only be read.

orixdj-error
deck.A.position = 30s
text
'deck.A.position' is read-only. [E-READONLY]

Fix: 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).

# E-RAMP

A ramp (->) is used where it cannot be.

Two causes:

  • -> outside an over block;
  • ramping a control that cannot be ramped: a switch, a text or a duration.
orixdj-error
over 4 beats { deck.A.keylock -> true }
text
'deck.A.keylock' (bool) cannot be ramped; set it with '='. [E-RAMP]

Fix: put the ramp inside over duration { … }, or set the control with =. Controls marked "read, write, ramp" in the reference can be ramped. See Timing.

# E-OVER

A statement is not allowed inside an over block. Only ramps, assignments, action calls, declarations and print are.

orixdj-error
over 4 beats {
    deck.A.volume -> -12dB
    wait 1 beat
}
text
Only ramps ('->'), assignments and actions are allowed inside 'over'. Move this statement outside the block. [E-OVER]

Fix: move the statement before or after the block. To do something during a ramp, schedule it with at before the over.

# E-CURVE

The curve name after curve is not one of linear, easeIn, easeOut, smooth, exp.

orixdj-error
over 4 beats curve wavy { mixer.crossfader -> 1 }
text
Unknown curve 'wavy'. Curves: linear, easeIn, easeOut, smooth, exp. [E-CURVE]

# E-UNDECLARED

A name is used that has not been declared.

Typical 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.

orixdj-error
tempo = master.bpm
text
'tempo' is not declared. Declare it first: let tempo = …  (or 'var' if it changes). [E-UNDECLARED]

Fix: declare it (let tempo = master.bpm), or correct the spelling. See Variables.

# E-CONST

Something that cannot change is assigned, or a top-level constant is not constant.

Causes: 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.

orixdj-error
let count = 0
count = count + 1
text
'count' was declared with 'let' and cannot change. Declare it with 'var'. [E-CONST]

Fix: declare the variable with var. Move a top-level let that reads live values into the automation.

# E-REDECLARED

A name is defined twice.

Causes: 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.

orixdj-error
let fade = 4 bars
let fade = 8 bars
text
'fade' is already declared in this block. [E-REDECLARED]

Fix: rename one of them, or use var and assign.

# E-UNBOUNDED

A while loop has no valid bound, or reached it.

At compile time: limit is missing, or is not a constant whole number from 1 to 10000.

orixdj-error
while deck.A.playing {
    wait 1 beat
}
text
A 'while' loop needs an iteration bound: while condition limit 64 { … }. [E-UNBOUNDED]

At run time: the loop made limit turns and its condition was still true.

text
The 'while' loop reached its limit without its condition becoming false. [E-UNBOUNDED]

Fix: add limit N. If giving up after N turns is expected, count the turns in the condition. See Loops.

# E-LIMIT

A fixed limit of the language or of the runtime is exceeded.

At 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.

orixdj-error
repeat 1000000 {
    wait 1 beat
}
text
A loop cannot run more than 10000 times. [E-LIMIT]

At 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 +.

Fix: 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.

# E-RECURSION

A function calls itself, directly or through other functions.

text
Function 'countdown' calls itself, directly or through other functions. Recursion is not allowed: automations must be bounded. [E-RECURSION]

Fix: use a loop. See Functions.

# E-PURE

A function that returns a value does something other than compute.

Causes, 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.

orixdj-error
fn slow(x: number) -> number {
    wait 1 beat
    return x
}

automation "X" {
    print(slow(1))
}
text
'wait' is not allowed in a function that returns a value. Use a function without a return type for timed procedures. [E-PURE]

Fix: remove the return type to make it a procedure, or pass live values in as arguments.

# E-RETURN

return is misused, or a value function may end without returning.

Causes: 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.

orixdj-error
if not deck.B.loaded {
    return
}
text
'return' is only valid inside a function. Use 'stop' to end the automation. [E-RETURN]

# E-ARGS

A call has the wrong number of arguments, or a builtin is given arguments it does not accept.

orixdj-error
deck.A.seek()
text
seek(position: duration) takes 1 argument, not 0. [E-ARGS]
orixdj-error
let lowest = min(1, 2dB)
text
min() expects two values of the same numeric type. Signature: min(a, b) -> same type [E-ARGS]

Fix: check the signature in the reference, or with help deck.A.seek in the console.

# E-EVENT

An event handler is wrong.

Causes: an event that does not exist (on deck.A.finished), on trigger without a number, on inside a loop, on inside a function.

orixdj-error
on trigger { deck.A.play() }
text
'on trigger' needs a trigger number: on trigger(1) { … }. [E-EVENT]

Fix: the events are beat, bar, trigger(n) and deck.X.trackEnd, play, pause, loaded, beat. Declare handlers in the automation, outside loops. See Events.

# E-LOOP

break or continue is used outside a loop.

orixdj-error
if deck.A.playing {
    break
}
text
'break' is only valid inside a loop. [E-LOOP]

Fix: 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.

# E-MATH

A calculation has no finite result, usually a division by zero.

orixdj-error
let ratio = 1 / 0
text
The result of '/' is not a finite number (division by zero?). [E-MATH]

The compiler finds it when the operands are constants; otherwise it is a run-time error. Fix: test the divisor first.

orixdj
let tempo = deck.B.trackBpm
if tempo > 0 {
    print(deck.A.bpm / tempo)
} else {
    print("deck B has no tempo")
}

# Errors that only occur while running

# E-ACTION

An action could not be performed in the current state of the rig. The message comes from the engine and says why.

Message Cause
Deck C has no track loaded. play(), cue(), seek(), jump(), loop() or hotcue() on an empty deck
Deck A: hot cue 3 is not set. hotcue(3) before any setHotcue(3)
Deck A has no previous loop. reloop() when no loop was ever set
Deck A: set a loop start first. loopOut() without loopIn()
Deck A: the loop end must be after the loop start. loopOut() at or before the loop start
The loop does not fit before the end of the track. loop() too close to the end
Deck A is playing; pause it before loading. load() or loadNext() on a playing deck
Deck A is playing; pause it before ejecting. eject() on a playing deck
Deck A has no beat grid; seek with seconds instead. seek(32 beats) on a track without analysis
The rack is full (8 effects). enable() of a ninth effect in one rack
No library track matches "…". load("…") with a title that is not in the library
orixdj-error
deck.A.hotcue(3)
text
Deck A: hot cue 3 is not set. [E-ACTION]

Fix: test the state before acting.

orixdj
if deck.C.loaded {
    deck.C.play()
} else {
    print("deck C is empty")
}

# E-BUDGET

The 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.

orixdj-error
var n = 0
repeat 10000 {
    n = n + 1
}
text
More than 20000 operations without a wait. Add a 'wait' inside the loop or reduce its work. [E-BUDGET]

Fix: put a wait in the loop, or reduce the number of turns. See Performance Guidelines.

# E-RATE

The script issued more than 512 parameter changes and actions within one beat. Ramps are not counted.

orixdj-error
repeat 2000 {
    mixer.crossfader = 0.5
}
text
More than 512 commands in one beat. The automation was stopped to protect the performance. [E-RATE]

Fix: a loop that writes controls needs a wait in its body. For smooth movement use over instead of many small steps.

# E-UNAVAILABLE

The script reads a value, or starts a ramp from a value, that the rig cannot provide at that moment.

text
'fx.echo.mix' cannot be read right now (the effect is not in the rack; call enable() first). [E-UNAVAILABLE]

In 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.

# E-INTERNAL

The 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.

# Warnings

Warnings do not stop a script from running. They point at things that are legal but probably not what you meant.

Code Message Meaning and fix
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.
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.
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.
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 ->.
W-RAMP 'path' is ramped twice in the same block; the last ramp wins. Remove one of the two ramps.
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.
orixdj
automation "Warnings" {
    over 1 bar {
        deck.A.volume = -6dB        // W-OVER: no ramp in this block
    }
    deck.A.volume = 0dB
    stop
    deck.A.pause()                  // W-UNREACHABLE
}

Two more warnings are produced while running and appear in the log, without a code:

text
line 9: 'at' names a position 4 beats in the past; running it now
line 12: 'wait until' names a position that has already passed

# Writing scripts that do not fail

  • Check before acting: if deck.B.loaded, if deck.B.trackBpm > 0, if not deck.B.playing.
  • Print the reason and stop when the situation is wrong.
  • Switch effects on from the script that uses them: if it fails, the effects it switched on are switched off.
  • 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).
  • Keep panic within reach.

# Code index

Code When In one line
E-SYNTAX compile The text does not follow the grammar
E-LEX compile Unreadable character, unterminated string or comment
E-UNIT compile Unknown unit after a number
E-EMPTY compile No automation in the script
E-TYPE compile, run Wrong type or unit
E-RANGE compile, run Constant outside its range; bad index, count or position
E-PATH compile Unknown or misused path
E-DECK compile Unknown deck letter
E-EFFECT compile Unknown effect
E-CAPABILITY compile Deck or effect not available in this setup
E-READONLY compile Writing a read-only property
E-RAMP compile, run -> outside over, or on a control that cannot be ramped
E-OVER compile, run Statement not allowed inside over
E-CURVE compile Unknown ramp curve
E-UNDECLARED compile Unknown variable or function
E-CONST compile Assigning to something constant
E-REDECLARED compile Name defined twice
E-UNBOUNDED compile, run while without a valid limit, or limit reached
E-LIMIT compile, run A fixed limit exceeded
E-RECURSION compile A function calls itself
E-PURE compile, run Side effect or timing in a value function
E-RETURN compile, run Misplaced or missing return
E-ARGS compile Wrong number or kind of arguments
E-EVENT compile Invalid event handler
E-LOOP compile break or continue outside a loop
E-MATH compile, run Non-finite result
E-ACTION run The rig refused an action
E-BUDGET run Too many operations without a wait
E-RATE run Too many commands in one beat
E-UNAVAILABLE run A value cannot be read
E-INTERNAL run Defect in the runtime
Files main
Menu

Theme