What does 'N/query.runSuiteQL error: Unexpected Error' mean in SuiteQL?

Nothing on its own. No error code, no character offset, no identifier name, no statement echo. Read it as "something in this statement is not supported on this path" and bisect the query until the error moves. Four different causes produced this exact string in one run.

Minimal reproduction

SELECT tal.subsidiary FROM transactionAccountingLine tal FETCH FIRST 1 ROWS ONLY

N/query.runSuiteQL error: Unexpected Error

That is the entire response. The column does not exist on the table, but the error never says so.

The fix for that case

Prove what the columns are first:

SELECT * FROM transactionAccountingLine FETCH FIRST 1 ROWS ONLY

The key set that comes back contains transaction, transactionline, account, accounttype, amount, amountunpaid, debit, credit and a handful more, and subsidiary is not among them. Null-valued columns come back as explicit keys rather than being omitted, and a twenty-row sample of this table returned the same key set as the single row.

Subsidiary lives on the line table. Join on both halves of the key and select it from there:

SELECT tl.subsidiary
FROM transactionAccountingLine tal
JOIN transactionLine tl ON tl.transaction = tal.transaction AND tl.id = tal.transactionline
FETCH FIRST 5 ROWS ONLY

Both predicates are required. Joining on transaction alone matches every accounting line against every line of the same transaction and multiplies the result, without erroring.

What else produced the same string

BUILTIN.CURRENCY_CONVERT(1, 1, 2, SYSDATE) and BUILTIN.CONSOLIDATE(1, 'INCOME', 'DEFAULT', 'DEFAULT', 1, SYSDATE, 'FULL') both returned bare Unexpected Error, so no working argument order was established for either. BUILTIN_RESULT.TYPE_CURRENCY(foreignamount) returned it too when run against a table where the column resolves, which is what establishes that this function is genuinely unsupported here rather than mistyped.

Not every BUILTIN failure is this opaque. Two probes returned errors that name the function and the problem:

N/query.runSuiteQL error: Search error occurred: Cannot build builtin function, validation failed. Enum type const doesn't exist: FIELD

N/query.runSuiteQL error: Search error occurred: Cannot build builtin function, validation failed. Wrong number of arguments for function PERIOD. There is no validate builtin / result function with 2 arguments

The first came from BUILTIN.HIERARCHY(subsidiary, 'FIELD'), the second from BUILTIN.PERIOD('LSFY', 'START'). In both the function exists and your arguments are wrong. Unexpected Error tells you neither.

Why this happens

Directly observed: the same string comes back from an unresolvable column and from three BUILTIN calls, and it is distinct both from the parse-error family, which echoes the statement with a token and an offset, and from the validation errors above.

The sharpest evidence is a matched pair. BUILTIN_RESULT.TYPE_CURRENCY(foreignamount) FROM transaction fails with syntax error ... near: FETCH, because that column does not exist on transaction. The identical expression FROM transactionLine, where the column does exist, fails with Unexpected Error. Same expression, two different strings, neither naming the real issue.

That pair also fixes the relationship between the two errors. An unresolvable column is the most common cause of syntax error ... near: FETCH, but it is not the only error an unresolvable column produces: the reproduction at the top of this page is exactly that shape and returns Unexpected Error instead. So the rule to keep is the action, not the diagnosis: if SuiteQL blames your FETCH clause, delete the FETCH clause and run again, because the second error names the real problem.

Nothing here shows what raises the string or at which stage. Treat the causes as observed causes, not a taxonomy.

How to tell if you are affected

Bisect in two moves. These are templates: substitute your own table, columns and predicate.

SELECT * FROM your_table FETCH FIRST 1 ROWS ONLY

Search the returned key set for every column your failing statement references. If one of them is missing, that is your bug, and no further step is needed.

SELECT 1 AS probe FROM your_table WHERE your_predicate FETCH FIRST 1 ROWS ONLY

If step 1 showed every referenced column present and step 2 runs clean, the expression you removed from the select list is the unsupported construct. If step 2 also returns Unexpected Error, the predicate is the unsupported part, not the select list. If step 2 returns a named error, that string is your diagnosis.

Do not generalise from one function to its family: TYPE_STRING, TYPE_INTEGER and TYPE_DATE all ran without error in the same session that TYPE_CURRENCY failed.

Scope: one production account on NetSuite 2026.1. Every probe behind this page ran entirely through N/query.runSuiteQL; the finding was not tested on the REST endpoint. Every error string above is NetSuite's own text verbatim. Not every statement quoted above is an instance of this error: some of them returned other strings and some ran clean, and they are here as controls, for comparison. The causes listed are the ones this run happened to hit, not a complete list of what can produce the string. Argument orders for CURRENCY_CONVERT and CONSOLIDATE were tried once each, so their failure means "this order was refused", not "the function is broken".