Error handling


System command: type \ at the debugger prompt q)) prompt to return to the interactive session.



Syntax: exit x

where x is a positive integer, exit terminates the q process with x as the exit code.

q)exit 0        / typical successful exit status

q)exit 42
guest@localhost:~$ echo $?
.z.exit (action on exit)

' (signal)

Syntax: 'emsg

where emsg is a symbol or char list, signal aborts evaluation and passes msg to the interpreter as a string.

The only way to detect a signal is to use trap.
Trap always receives a string regardless of the type of x.

Signal has some restrictions

q)f 1         / signals a type error indicating ' will not signal a number
q)f"a"        /q will not signal a char
Using an undefined word signals the word as an error
which is indistinguishable from

. @ (trap)

Syntax: @[f;fx;e]
Syntax: .[g;gg;e]


  • f is a unary function and fx is its argument
  • g is a multi-argument function and gg is a list of its arguments
  • e is an expression, typically a function

Trap will evaluate function e if evaluation of f or g fails. It is similar to try/catch in other languages.

When there is no signal, @ behaves like binary @.

When there is a signal the result of the trap is e.
q)@[{'x};"signal this";`err]
If e is a function, it is called with the signal as argument.
q)@[2+;"42";{"Caught: ",x}]
"Caught: type"
This can be used to return a result unambiguously indicating whether the function succeeded. Here, the first item of the pair indicates success or failure, while the second item is either the result or the error. This is useful when 0 or () might be valid results.

Limit of the trap

Trap catches only errors signalled in the applications of f or g. Errors in the evaluation of fx or gg themselves are not caught.

  [0]  @[2+;"42"+3;`err]

@[f;fx;e] is equivalent to .[f;enlist fx;e]. "dot" trap is used for multi-argument f.

q)@[parse;"22 1b1 44";::]

When e is not a function

If e is a function it will be evaluated only if f or g fails. It will however be parsed before any of the other expressions are evaluated.

  [0]  @[2+;"42";{)}]
If e is any other kind of expression it will always be evaluated – and first, in the usual right-to-left sequence. In this respect trap is unlike try/catch in other languages.
q)@[string;42;a:100] / expression not a function
q)a // but a was assigned anyway
q)@[string;42;{b::99}] / expression is a function
q)b // not evaluated
  [0]  b
For most purposes, you will want e to be a function.


Runtime errors

error example explanation
access attempt to read files above directory, run system commands or failed usr/pwd
accp tried to accept an incoming tcp/ip connection but failed to do so
adict d[::]:x blocked assignment ('nyi)
arch attempt to load file of wrong endian format
assign cos:12 attempt to reuse a reserved word
badtail incomplete transaction at end of logfile, get good (count;length) with -11!(-2;:file)`
cast `sym$`xxx attempt to enumerate invalid value (`xxx not in sym in example)
conn too many incoming connections (1022 max)
d8 the log had a partial transaction at the end but q couldn't truncate the file.
domain !-1 out of domain
elim more than 57 distinct enumerations
from select a b badly formed select statement
glim limit on number of vectors with a `g# attribute, unlimited since 3.2
hwr handle write error, can't write inside a peach
insert attempt to insert a record with a key that already exists
length ()+!1 incompatible lengths
limit 0W#2 tried to generate a list longer than 2,000,000,000
loop a::a dependency or transitive closure loop
mismatch columns that can't be aligned for R,R or K,K
mlim limit on number of concurrently mapped nested vectors, currently 65530
nyi not yet implemented
noamend can't change global state inside an amend
noupdate update not allowed when using negative port number
nosocket can only open/use sockets in main thread
os operating system error
parse invalid syntax
part something wrong with the partitions in the HDB
pl peach can't handle parallel lambdas (2.3 only)
Q7 nyi op on file nested array
rank +[2;3;4] invalid rank or valence
rb encountered a problem whilst doing a blocking read
s-fail `s#2 1 cannot apply `s# to data (not ascending values)
splay nyi op on splayed table
stack {.z.s[]}[] ran out of stack space
step attempt to upsert into stepped (`s#) dictionary
stop user interrupt (Ctrl-c) or time limit (-T)
stype '42 invalid type used to signal
threadview views can only be calculated from the main thread
trunc the log had a partial transaction at the end but q couldn't truncate the file
type til 2.2 wrong type
u-fail `u#1 1 cannot apply `u# to data (not unique values)
unmappable when saving partitioned data, each column must be mappable
value no value
vd1 attempted multithread update
view trying to re-assign a view to something else
wsfull malloc failed. ran out of swap (or addressability on 32 bit). or hit -w limit
XXX value error (XXX undefined)

System errors (file and IPC)

error example explanation
XXX:YYY read0`:invalidname.txt XXX is from kdb+, YYY from the OS

XXX from addr, close, conn, p (from -p), snd, rcv or (invalid) filename

Parse errors (execute or load)

error example explanation
[({])}" count abc" open paren, bracket, brace or double-quote
branch a branch (if; do; while; $[.;.;.]) more than 255 byte codes away
char invalid character
constants too many constants (max 96)
globals too many global variables (32 max)
locals too many local variables (24 max)
params too many parameters (8 max)

License errors

error explanation
cores too many cores
exp expiry date passed
host unlicensed host
k4.lic k4.lic file not found, check QHOME/QLIC
os unlicensed OS
srv attempt to use client-only license in server mode
upd attempt to use version of kdb+ more recent than update date
user unlicensed user
wha invalid system date