Error Handling

The SDK provides structured errors with codes, categories, and recovery hints.

ArcflowError#

All errors from the engine are wrapped in ArcflowError:

import { ArcflowError } from '@ozinc/arcflow'
 
try {
  db.query("INVALID QUERY")
} catch (err) {
  if (err instanceof ArcflowError) {
    console.log(err.code)        // "EXPECTED_KEYWORD"
    console.log(err.category)    // "parse"
    console.log(err.message)     // "Expected MATCH, CREATE, MERGE, ..."
    console.log(err.suggestion)  // "Expected MATCH or CREATE" (when available)
  }
}

Error categories#

Category	When	Example Codes
`parse`	Query syntax is invalid	`EXPECTED_KEYWORD`, `UNEXPECTED_TOKEN`, `PARSE_ERROR`
`validation`	Query is syntactically valid but semantically wrong	`UNKNOWN_PROCEDURE`, `TYPE_MISMATCH`, `INVALID_ARGUMENT`
`execution`	Runtime error during query execution	`UNKNOWN`, general execution failures
`integration`	Infrastructure or lifecycle error	`LOCK_POISONED`, `HANDLE_BUSY_CONCURRENT_WRITER`

Error code reference#

Code	Category	Meaning	Fix
`EXPECTED_KEYWORD`	parse	Query syntax wrong	Check MATCH/CREATE/MERGE syntax
`UNEXPECTED_TOKEN`	parse	Unexpected token in query	Run `CALL db.help()`
`PARSE_ERROR`	parse	General parser failure	Verify the GQL/Cypher form against `docs/worldcypher`
`UNKNOWN_PROCEDURE`	validation	Procedure doesn't exist	Run `CALL db.procedures()`
`INVALID_ARGUMENT`	validation	Procedure called with wrong-shape arg	Check the procedure's `recovery_suggestion`
`WORKFLOW_NOT_FOUND`	validation	Workflow name doesn't exist	Run `CALL arcflow.workflow.list`
`STEP_NOT_FOUND`	validation	Step name not in workflow	Check step name spelling
`EXECUTION_CONTEXT_MISMATCH`	integration	Context guard failed	`CALL db.setExecutionContext(...)` first
`UNKNOWN_EXECUTION_CONTEXT`	validation	Invalid context string	Use `local_cpu`, `local_gpu`, or `distributed`
`TEMPORAL_WAL_NOT_WIRED`	integration	AS OF seq used without WAL context	Open the store with WAL enabled (`open()` or `openInMemory()` with sync options)
`LOCK_POISONED`	integration	Internal mutex poisoned	Restart the process
`HANDLE_BUSY_CONCURRENT_WRITER`	integration	Another writer holds the handle	Retry after the writer commits, or use a session-bound handle

Common errors and fixes#

Parse errors#

// Wrong:
db.query("FIND (n:Person)")  // EXPECTED_KEYWORD — "FIND" is not a keyword
 
// Right:
db.query("MATCH (n:Person) RETURN n")

Missing RETURN clause#

// Wrong:
db.query("MATCH (n:Person)")  // Needs a RETURN
 
// Right:
db.query("MATCH (n:Person) RETURN n.name")

Using closed database#

db.close()
db.query("RETURN 1")  // throws — the handle is invalid after close()

Programmatic error handling#

try {
  db.query(userProvidedQuery)
} catch (err) {
  if (err instanceof ArcflowError) {
    switch (err.category) {
      case 'parse':
        return { error: 'Invalid query syntax', detail: err.message }
      case 'validation':
        return { error: 'Query validation failed', detail: err.message }
      case 'execution':
        return { error: 'Query execution failed', detail: err.message }
      case 'integration':
        return { error: 'Database error', detail: err.message }
    }
  }
  throw err  // Re-throw unexpected errors
}

Health check#

Use isHealthy() to check if the database is operational:

if (!db.isHealthy()) {
  // Reinitialize or alert
}

Error Handling

ArcflowError#

Error categories#

Error code reference#

Common errors and fixes#

Parse errors#

Missing RETURN clause#

Using closed database#

Programmatic error handling#

Health check#

See Also#

Error Handling

ArcflowError#

Error categories#

Error code reference#

Common errors and fixes#

Parse errors#

Missing RETURN clause#

Using closed database#

Programmatic error handling#

Health check#

See Also#