Error codes

When a statement is refused, the answer says what happened and how to put it right. Every message starts with a code, and the code names a family: 1xxx for syntax, 2xxx for values, 3xxx for permission, 4xxx for tables and columns, 5xxx for arguments, 6xxx for writes, 7xxx for dates, 8xxx for formulas and 9xxx for the system. This page lists each code with what to do.

Reading a refusal

A refused statement returns {"success": false, "error": "[HTQL-1003] …"}. The code is the part in square brackets. The text after it names the part of your statement that caused it, and it is what the tables below summarise.

A few failures reach you from the database itself, for example a join that names a table not in the statement, and carry no HTQL code. The message names the database relation or column involved.

1xxx: syntax and parsing

CodeWhat happenedHow to recover
HTQL-1001A statement or clause could not be parsed, for example a NEST with no ONRead the message: it names the missing part
HTQL-1002A clause is malformed, for example an empty INSERT record or a JOIN ON list with an odd number of namesWrite the clause as its entry shows
HTQL-1003The statement is not written in HTQL's grammarCheck the text near the place the message names, for example quote a SORT term
HTQL-1004The function or clause is not supported in this positionCheck the name and its spelling
HTQL-1005The function category is not supportedCheck the category name
HTQL-1006The feature is not supported yetUse another statement
HTQL-1009An expression is not valid, for example a bare string used as a FILTER conditionWrite it as the entry shows
HTQL-1010An arithmetic expression is not validCheck the operands and operators
HTQL-1011A comparison operator is not validUse an operator listed in the FILTER entry
HTQL-1012A logical operator is not validUse AND, OR or NOT
HTQL-1013A logical expression is not structured correctlyCheck the brackets of AND, OR and NOT
HTQL-1014An unexpected form was found in a returned valueCheck the RETURN expression
HTQL-1015A LOOKUP was used where only a LET value is allowedMove the LOOKUP into a LET
HTQL-1016A GET clause is not in the form GET(collection, alias)Write GET(table) or GET(table, alias)
HTQL-1017The getter method is not supportedUse GET
HTQL-1018The getter clause is not spelt correctlyCheck the spelling against the list the message gives
HTQL-1019The statement is not implementedUse another statement

2xxx: types and values

CodeWhat happenedHow to recover
HTQL-2001An argument or name is not valid: a column that does not exist, a bad SORT direction, a LEARN column that is not in GROUP, or a write that matched no rowRead the message: it names the column or the rule
HTQL-2002A value is not validCheck the value's type
HTQL-2003A number is outside the allowed rangeUse a number inside the range
HTQL-2004A number is not in a valid formatWrite the number in digits
HTQL-2005A value could not be convertedCheck the value's type
HTQL-2006The return type is not validCheck the RETURN expression
HTQL-2008A variable is not definedDefine it with LET before you use it
HTQL-2009A variable name is not valid: names use letters, digits and underscoresRename the variable
HTQL-2010A variable is not knownDefine it with LET
HTQL-2011A statement is missing a required part, for example an UPDATE or REMOVE with no FILTERAdd the part the message names
HTQL-2012A value failed a validation ruleRead the message for the rule

3xxx: permission

CodeWhat happenedHow to recover
HTQL-3001Access is denied on a resourceAsk the administrator of your tenant for access
HTQL-3002The caller is not authorised, with a reason in square bracketsUse the reason to see what is missing
HTQL-3003The table is not registered as readableCheck the table's name
HTQL-3004The table is protected and cannot be deleted fromChoose another table
HTQL-3005The table is protected and cannot be truncatedChoose another table
HTQL-3006A field name is ambiguousWrite the field with its table, as the message suggests
HTQL-3007A field is not knownCheck the field's name
HTQL-3008The report is not a registered reportCheck the report's name
HTQL-3009The report is registered but not implementedUse another report
HTQL-3010The table is read-only for tenantsWrite to a table your account may write

4xxx: tables, columns and results

CodeWhat happenedHow to recover
HTQL-4001The table does not exist on the channelCheck the table's name and channel
HTQL-4002The channel does not existCheck the channel's name
HTQL-4003The collection does not existCheck the collection's name
HTQL-4004The name already existsChoose another name
HTQL-4005A required field is missingAdd the field the message names
HTQL-4006A key is not valid: keys use letters, digits, dots and underscoresRename the key
HTQL-4007The database is not connectedTry again, and contact your administrator if it continues
HTQL-4010A RETURN query has no JSON objectWrite RETURN with an object
HTQL-4011A RETURN statement has a missing keyGive every value a key
HTQL-4012A RETURN statement has a missing valueGive every key a value, or return an object
HTQL-4013A column in a FILTER does not exist on the tableCheck the column's name
HTQL-4014A column in an UPDATE record does not exist on the tableCheck the column's name
HTQL-4015A column in an INSERT record does not exist on the tableCheck the column's name
HTQL-4016A name was refused as unsafeUse letters, digits and underscores

5xxx: arguments

CodeWhat happenedHow to recover
HTQL-5001A function or clause needs an exact number of arguments, for example SHOW with none, or JOIN without ONGive it the number the message names
HTQL-5002The function takes no argumentsRemove the arguments
HTQL-5003Too many arguments were givenRemove the extra arguments
HTQL-5004Too few arguments were givenAdd the missing arguments
HTQL-5005An argument has the wrong typeCheck the function's arguments

6xxx: writes

CodeWhat happenedHow to recover
HTQL-6001A write could not be carried out, with the reason in the messageRead the reason
HTQL-6002A value in the statement is not validCheck the value
HTQL-6003A key is too largeUse a shorter key
HTQL-6004A value is too largeStore a smaller value
HTQL-6005A key-value key is not validUse letters, digits, dots and underscores
HTQL-6006The collection already existsChoose another name
HTQL-6007The collection schema already existsChoose another name
HTQL-6008A number could not be converted for storageCheck the number
HTQL-6010A FILTER is missing a required field for this tableAdd the field the message names
HTQL-6011An edge collection is not named like name_edgeUse lower case with the _edge suffix
HTQL-6012An edge statement is not valid, for example a missing _from, an end that does not exist or an attempt to move an endRead the message for the rule

7xxx: dates and times

CodeWhat happenedHow to recover
HTQL-7001A date or time value is not validWrite it as a date such as 2026-01-15
HTQL-7002A date range is not validPut the earlier date first
HTQL-7003A time is not in a valid formatCheck the time's format
HTQL-7004A date unit is not validUse a unit the function lists

8xxx: formulas

CodeWhat happenedHow to recover
HTQL-8001A formula has no value to give (#N/A)Check that the value it looks up exists
HTQL-8002A formula divided by zero (#DIV/0!)Check the divisor
HTQL-8003A formula has a value of the wrong kind (#VALUE!)Check the argument types
HTQL-8004A formula has a number that is not valid (#NUM!)Check the numbers
HTQL-8005A formula failed, with the reason in the messageRead the reason
HTQL-8006A formula failed, with the reason in the messageRead the reason
HTQL-8007A computation failedCheck the inputs

9xxx: the system

CodeWhat happenedHow to recover
HTQL-9001The database reported an error, with the reason in the messageRead the reason, and try again
HTQL-9002A value could not be serialisedCheck the value
HTQL-9004An identifier could not be handledCheck the identifier
HTQL-9005A text value is not valid UTF-8Send valid text
HTQL-9006The error is not knownContact support with the statement
HTQL-9007A FLOW step reached its maximum error countSee the FLOW reference
HTQL-9008The FLOW is complete and has no more stepsNo action is needed
HTQL-9009The FLOW is not validSee the FLOW reference