Errors

Errors

Every response is valid JSON, including failures. QQL never returns a malformed string, and the C ABI never returns null.

{
  "ok": false,
  "query": "Q:2:5-1",
  "error": {
    "code": "QQL_INVALID_RANGE",
    "message": "Range start cannot be greater than range end",
    "position": 4
  }
}

position is a byte offset into the query, and is present only for errors that have one. It is never emitted as a placeholder 0.

Codes

Syntax — the query is malformed

Code	Cause	Example
QQL_EMPTY_QUERY	nothing but whitespace	""
QQL_INVALID_CHARACTER	a character or token that cannot appear here	Q:2*3, Q:1:1-5:3
QQL_EXPECTED_SOURCE	a reference must start with a code, number or term	;, :2
QQL_EXPECTED_COLON	a : was required	Q
QQL_EXPECTED_NUMBER	a number was required, or it overflowed u32	Q:, Q:A, Q:2:1-
QQL_INVALID_RANGE	range start greater than its end	Q:2:5-1
QQL_EXPECTED_TEXT	a quoted term was required, or it was empty	Q:1:""
QQL_UNTERMINATED_TEXT	a term was opened and never closed	Q:1:"abc

Semantic — the query parses but names nothing

Code	Cause	Example
QQL_UNKNOWN_SOURCE	no source registered under that code	XYZ:1
QQL_REFERENCE_NOT_FOUND	out of bounds for that collection	Q:0, Q:115, Q:2:999
QQL_UNSUPPORTED	the source cannot do what was asked	q:1: + a backtick term without the feature

Storage and internal

Code	Cause
QQL_DATA_FILE_NOT_FOUND	a file the resolver needed is missing
QQL_INVALID_DATA_FILE	a file exists but could not be read or parsed
QQL_INTERNAL_ERROR	a bug in QQL, or a null pointer across the C ABI

Which layer rejects what

This is the design in miniature. The parser knows only the grammar:

Q:500:999    parses cleanly → the Quran resolver rejects it   QQL_REFERENCE_NOT_FOUND
XYZ:1:2      parses cleanly → the registry rejects it         QQL_UNKNOWN_SOURCE
Q:2:5-1      the parser rejects it                            QQL_INVALID_RANGE

So a syntax error means the query is wrong; a semantic error means the query is fine but the reference does not exist.

Things that are not errors

• A search matching nothing returns "ok": true with an empty results.
• A ranked search returning fewer than its cap — weak matches are dropped.
• A missing qql-sources.json — most installations have no custom sources. A malformed one is QQL_INVALID_DATA_FILE.

Reading errors in each interface

CLI — the JSON goes to stdout, exit code 1.

Rust — execute returns Result<Vec<Record>, Error>; Error::code() and Error::position() give the wire values. execute_json never fails and serializes the error instead.

C — qql_context_execute never returns null and never returns malformed JSON; a null context, a null query and invalid UTF-8 all come back as {"ok":false,…}.

Dart — execute throws QqlException carrying code, message and position. executeJson returns the raw string and never throws.