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
| Code | What happened | How to recover |
|---|---|---|
HTQL-1001 | A statement or clause could not be parsed, for example a NEST with no ON | Read the message: it names the missing part |
HTQL-1002 | A clause is malformed, for example an empty INSERT record or a JOIN ON list with an odd number of names | Write the clause as its entry shows |
HTQL-1003 | The statement is not written in HTQL's grammar | Check the text near the place the message names, for example quote a SORT term |
HTQL-1004 | The function or clause is not supported in this position | Check the name and its spelling |
HTQL-1005 | The function category is not supported | Check the category name |
HTQL-1006 | The feature is not supported yet | Use another statement |
HTQL-1009 | An expression is not valid, for example a bare string used as a FILTER condition | Write it as the entry shows |
HTQL-1010 | An arithmetic expression is not valid | Check the operands and operators |
HTQL-1011 | A comparison operator is not valid | Use an operator listed in the FILTER entry |
HTQL-1012 | A logical operator is not valid | Use AND, OR or NOT |
HTQL-1013 | A logical expression is not structured correctly | Check the brackets of AND, OR and NOT |
HTQL-1014 | An unexpected form was found in a returned value | Check the RETURN expression |
HTQL-1015 | A LOOKUP was used where only a LET value is allowed | Move the LOOKUP into a LET |
HTQL-1016 | A GET clause is not in the form GET(collection, alias) | Write GET(table) or GET(table, alias) |
HTQL-1017 | The getter method is not supported | Use GET |
HTQL-1018 | The getter clause is not spelt correctly | Check the spelling against the list the message gives |
HTQL-1019 | The statement is not implemented | Use another statement |
2xxx: types and values
| Code | What happened | How to recover |
|---|---|---|
HTQL-2001 | An 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 row | Read the message: it names the column or the rule |
HTQL-2002 | A value is not valid | Check the value's type |
HTQL-2003 | A number is outside the allowed range | Use a number inside the range |
HTQL-2004 | A number is not in a valid format | Write the number in digits |
HTQL-2005 | A value could not be converted | Check the value's type |
HTQL-2006 | The return type is not valid | Check the RETURN expression |
HTQL-2008 | A variable is not defined | Define it with LET before you use it |
HTQL-2009 | A variable name is not valid: names use letters, digits and underscores | Rename the variable |
HTQL-2010 | A variable is not known | Define it with LET |
HTQL-2011 | A statement is missing a required part, for example an UPDATE or REMOVE with no FILTER | Add the part the message names |
HTQL-2012 | A value failed a validation rule | Read the message for the rule |
3xxx: permission
| Code | What happened | How to recover |
|---|---|---|
HTQL-3001 | Access is denied on a resource | Ask the administrator of your tenant for access |
HTQL-3002 | The caller is not authorised, with a reason in square brackets | Use the reason to see what is missing |
HTQL-3003 | The table is not registered as readable | Check the table's name |
HTQL-3004 | The table is protected and cannot be deleted from | Choose another table |
HTQL-3005 | The table is protected and cannot be truncated | Choose another table |
HTQL-3006 | A field name is ambiguous | Write the field with its table, as the message suggests |
HTQL-3007 | A field is not known | Check the field's name |
HTQL-3008 | The report is not a registered report | Check the report's name |
HTQL-3009 | The report is registered but not implemented | Use another report |
HTQL-3010 | The table is read-only for tenants | Write to a table your account may write |
4xxx: tables, columns and results
| Code | What happened | How to recover |
|---|---|---|
HTQL-4001 | The table does not exist on the channel | Check the table's name and channel |
HTQL-4002 | The channel does not exist | Check the channel's name |
HTQL-4003 | The collection does not exist | Check the collection's name |
HTQL-4004 | The name already exists | Choose another name |
HTQL-4005 | A required field is missing | Add the field the message names |
HTQL-4006 | A key is not valid: keys use letters, digits, dots and underscores | Rename the key |
HTQL-4007 | The database is not connected | Try again, and contact your administrator if it continues |
HTQL-4010 | A RETURN query has no JSON object | Write RETURN with an object |
HTQL-4011 | A RETURN statement has a missing key | Give every value a key |
HTQL-4012 | A RETURN statement has a missing value | Give every key a value, or return an object |
HTQL-4013 | A column in a FILTER does not exist on the table | Check the column's name |
HTQL-4014 | A column in an UPDATE record does not exist on the table | Check the column's name |
HTQL-4015 | A column in an INSERT record does not exist on the table | Check the column's name |
HTQL-4016 | A name was refused as unsafe | Use letters, digits and underscores |
5xxx: arguments
| Code | What happened | How to recover |
|---|---|---|
HTQL-5001 | A function or clause needs an exact number of arguments, for example SHOW with none, or JOIN without ON | Give it the number the message names |
HTQL-5002 | The function takes no arguments | Remove the arguments |
HTQL-5003 | Too many arguments were given | Remove the extra arguments |
HTQL-5004 | Too few arguments were given | Add the missing arguments |
HTQL-5005 | An argument has the wrong type | Check the function's arguments |
6xxx: writes
| Code | What happened | How to recover |
|---|---|---|
HTQL-6001 | A write could not be carried out, with the reason in the message | Read the reason |
HTQL-6002 | A value in the statement is not valid | Check the value |
HTQL-6003 | A key is too large | Use a shorter key |
HTQL-6004 | A value is too large | Store a smaller value |
HTQL-6005 | A key-value key is not valid | Use letters, digits, dots and underscores |
HTQL-6006 | The collection already exists | Choose another name |
HTQL-6007 | The collection schema already exists | Choose another name |
HTQL-6008 | A number could not be converted for storage | Check the number |
HTQL-6010 | A FILTER is missing a required field for this table | Add the field the message names |
HTQL-6011 | An edge collection is not named like name_edge | Use lower case with the _edge suffix |
HTQL-6012 | An edge statement is not valid, for example a missing _from, an end that does not exist or an attempt to move an end | Read the message for the rule |
7xxx: dates and times
| Code | What happened | How to recover |
|---|---|---|
HTQL-7001 | A date or time value is not valid | Write it as a date such as 2026-01-15 |
HTQL-7002 | A date range is not valid | Put the earlier date first |
HTQL-7003 | A time is not in a valid format | Check the time's format |
HTQL-7004 | A date unit is not valid | Use a unit the function lists |
8xxx: formulas
| Code | What happened | How to recover |
|---|---|---|
HTQL-8001 | A formula has no value to give (#N/A) | Check that the value it looks up exists |
HTQL-8002 | A formula divided by zero (#DIV/0!) | Check the divisor |
HTQL-8003 | A formula has a value of the wrong kind (#VALUE!) | Check the argument types |
HTQL-8004 | A formula has a number that is not valid (#NUM!) | Check the numbers |
HTQL-8005 | A formula failed, with the reason in the message | Read the reason |
HTQL-8006 | A formula failed, with the reason in the message | Read the reason |
HTQL-8007 | A computation failed | Check the inputs |
9xxx: the system
| Code | What happened | How to recover |
|---|---|---|
HTQL-9001 | The database reported an error, with the reason in the message | Read the reason, and try again |
HTQL-9002 | A value could not be serialised | Check the value |
HTQL-9004 | An identifier could not be handled | Check the identifier |
HTQL-9005 | A text value is not valid UTF-8 | Send valid text |
HTQL-9006 | The error is not known | Contact support with the statement |
HTQL-9007 | A FLOW step reached its maximum error count | See the FLOW reference |
HTQL-9008 | The FLOW is complete and has no more steps | No action is needed |
HTQL-9009 | The FLOW is not valid | See the FLOW reference |