Errors and failure modes

What can go wrong, what the runtime raises when it does, and which failures stop a payload (fail closed) versus let it through (fail open). Read the fail-open section before you go to production.

Catching runtime exceptions#

Every error the runtime raises derives from HelixorRuntimeError, and the classes on this page are exported from helixor_runtime, except the two subclasses LicenseRevokedAuthorityError and PlaybookParseError: catch their parents, LicenseSignatureInvalidError and CompilerError. Catch the base class around every evaluation, and never forward a payload that was not evaluated.

from helixor_runtime import DeveloperQuotaExceededError, HelixorRuntimeError

try:
    result = engine.evaluate(text)
except DeveloperQuotaExceededError:
    raise PayloadRejected("rate limited")      # back off and retry later
except HelixorRuntimeError as exc:
    log.error("helixor evaluation failed: %s", type(exc).__name__)
    raise PayloadRejected(type(exc).__name__) from exc   # never forward the payload

The exceptions that do not derive from it are FileNotFoundError and ValueError from load_pack() for a bad path or argument, and NativeRuntimeUnavailableError from the generated SDK client, which is not exported either. Some classes also derive from a built-in type for compatibility: StreamBlockedError from RuntimeError, UnsupportedPackDeclarationError from ValueError. In the next release: RemovedCapabilityError also from AttributeError, DecisionBudgetExceededError from RuntimeError, BeliefSnapshotError from ValueError.

Evaluation#

evaluate() never raises because of what a string says. Empty text evaluates as clean.

Licenses#

All license file errors share the base class LicenseError. See License file for the checks.

A license file that is not valid JSON, or is missing a section such as identity, fails with a JSON or key error rather than a LicenseError. Treat any error while loading a license as fatal.

Packs and compilation#

The CLI turns each of these into one line on standard error and exit code 1; see CLI.

HTTP status codes#

WebSocket errors arrive as {"type": "error", "message": "…"}. An error inside a handler also closes the connection. Without the bearer token, the connection is closed with code 1008. See HTTP API.

Fails closed#

These checks stop processing with an error. No partial result is returned.

• A license signature that is missing or invalid, or a license that is not yet valid or is past its grace period.
• A pack the license does not allow, or a declared solver the license does not allow.
• A pack sealed for a different license, a modified pack, or a failed integrity check.
• A fatal match in stream_filter / astream_filter (raises) or in a streaming session (blocked chunk, nothing further emitted).
• Developer quota or rate exceeded, when the key's enforcement mode is fail-closed.
• load_pack() with a missing pack or license file.
• A playbook or pack that declares something the engine does not execute, and a pack rule whose condition cannot be evaluated.
• A dict payload the engine cannot read.
• A service started on a non-loopback address without a token, or with a wildcard CORS origin.

Known fail-open paths in 0.2.1#

In these cases the runtime does not raise, and a payload or text can get through. Guard against each one in your integration. 0.2.1 closed the other paths listed for 0.2.0: load_pack with a missing file, a contact match overriding a custom block, compiled-pack rules skipped when a built-in check matched, invalid or unsupported rules skipped silently, redact rules that did not redact, license_key bypassing a served pack, and damaged text from short streaming chunks.

For how to design around these, see Reliability and Troubleshooting.