Skip to content
OnchainQueries

Results

Errors

Errors identify the stage that rejected or failed the query, so you know whether to change the SQL, the table name, or the expectations.

Error shapes

ErrorStageWhat to do
only SELECT or WITH is allowedRead-only gateThe statement is not a read-only query. Remove any data or schema modification.
exactly one SQL statement is allowedRead-only gateMultiple statements or misplaced semicolons were found. Submit one statement.
keyword "..." is not allowedRead-only gateA statement keyword that writes, configures or introspects. The full list is below.
table function "..." is not allowedRead-only gateA table function that would read from somewhere other than the catalog.
the system catalog is not accessibleRead-only gateAnything under system. is out of reach. Use the dataset catalog instead.
unterminated quoted value / unterminated SQL commentRead-only gateThe statement could not be scanned to the end. Close the quote or the comment.
OnchainQL parse errorParserThe generic SQL parser did not accept the syntax. Simplify and reintroduce clauses one at a time.
every query must bound the time range it readsPlannerA SELECT that reads a source table has no lower bound on ts. Add one inside that SELECT, not on an enclosing query.
table ... is not in the allowed Solana catalogCatalog resolutionThe relation is not a live OnchainQueries table or alias. Check the name against the dataset catalog.
... is not compatibility-safe yetCompatibility layerOnchainQueries deliberately rejects a function whose underlying namesake has different semantics.
complex approx_percentile arguments...Compatibility layerThe call is outside the supported two-argument form.
this UNNEST shape is not pushdown-compatibleCompatibility layerRewrite to the documented cross-join form over one column identifier.
TRY_CAST hybrid execution...Hybrid executionThe query exceeds the one-table restriction — no CTEs, joins or set operations alongside TRY_CAST.
ClickHouse ...BackendParsing succeeded but the backend rejected the function, type or operation.
source ... changed...ConsistencyOnchainQueries detected changing source data and will retry or fail consistently rather than publish a mixed result.

What the read-only gate refuses

Every query is scanned before it runs. Quoted values and comments are skipped, so SELECT 'drop table x' is a perfectly good query — only a real keyword in a real position is refused. These are the exact lists.

Statement keywords. Refused anywhere in the query:

alter · attach · create · delete · detach · drop · grant · insert · kill · optimize · rename · revoke · set · settings · system · truncate · update · use

Table functions. Refused when called, which is why null as a value and count(*) are both fine:

azureblobstorage · cluster · clusterallreplicas · deltalake · dictionary · executable · executablepool · file · generaterandom · hdfs · hudi · iceberg · input · jdbc · loop · merge · mongodb · mysql · namedcollection · null · numbers · odbc · postgresql · redis · remote · remotesecure · s3 · s3cluster · sqlite · url · values · view · zeros

CLI-level failures

  • invalid API token — run query login with an active query_sk_ key, or set QUERY_API_TOKEN in the current shell.
  • Connection refused, DNS or timeout — check that the machine can reach engine.onchainqueries.com and results.onchainqueries.com over HTTPS. The addresses are embedded in the release binary.
  • query limit reached; retry later — the service is at its active-query limit.
  • Parameter errors — every {{name}} needs exactly one matching --param, with a supported type and no unused parameters.
  • Size or checksum mismatch — rerun query attach with the same query ID. If it persists, preserve the error and contact the operator.

Debugging a failed query

Run query status QUERY_ID and inspect the error field. Syntax problems, read-only enforcement, unsupported function translations and source changes during execution all cause explicit failures with distinct messages.

Port an existing analytical query incrementally — verify the table coverage in tables & naming, replace quoted parameters, start with the core projection and filters, then add functions, joins, windows and arrays one at a time. Each addition that fails tells you exactly which feature is unsupported.