Error Reference

BlazeRules separates errors into two policy layers. Rule and schema activation is strict: an invalid ruleset is rejected before activation. Per-record ingest is tolerant by default: one malformed record does not abort a batch. The error domain identifies whether remediation belongs in ruleset activation or record ingestion.

📘

Activation and ingest policy

Ruleset validation is strict because it occurs before activation. Record ingestion defaults to skip-and-count so malformed rows do not terminate a stream. HARD_FAIL provides strict ingest behavior.

Layer 1 — strict activation

load_rules(...) and explicit schema binding compile and validate the complete configuration before activation. The following conditions fail before activation, so an invalid ruleset never becomes active:

• Bad YAML — the file does not parse.
• Unknown fields — a rule or config key the parser does not recognize.
• Unknown operator — an op that is not one of the supported operators is rejected (UNKNOWN_OP); it is never silently ignored.
• Unknown action — an action that is not flag / block / score / review / approve is rejected (UNKNOWN_ACTION); a typo cannot silently become a different action.
• Malformed nested condition — a parse error anywhere inside an and / or / not tree fails the whole rule; nested errors are never swallowed.
• Condition nesting too deep — an and/or/not tree or a parenthesized sql: expression nested beyond the depth limit is rejected instead of risking a stack overflow.
• Duplicate rule IDs — two rules share an id.
• Invalid regex — a regex / not_regex pattern RE2 rejects.
• Bad lookup files — a missing CSV, wrong columns, or unparseable rows for a referenced lookup.
• Type / operator mismatches — an operator applied to an incompatible field type.

Two ONNX-specific cases fail at the same layer when the library was built with BLAZERULES_ENABLE_ONNX=OFF:

• A model_score rule is rejected at compile time.
• register_model(name, path) throws.

🚧

A failed activation does not replace a running ruleset

If activation fails during a hot reload, the previous ruleset remains active.

Layer 2 — tolerant ingest

Once rules are active, two EngineConfig modes govern per-record failures. The defaults skip or null invalid data; hard-fail modes stop the batch.

import blazerules

config = blazerules.EngineConfig()
config.ingest_error_mode = blazerules.IngestErrorMode.SKIP_AND_COUNT          # default
config.type_mismatch_mode = blazerules.TypeMismatchMode.NULL_ON_TYPE_ERROR    # default

Per-batch BatchResult fields report ingest failures: messages_skipped, error_counts, and error_samples. A malformed row in an NDJSON stream is recorded and skipped under the default policy. Each error sample and SKIP_TO_DEAD_LETTER record includes the error code, column_name, and parser message, such as invalid JSON near field 'metrics'. See Observability.

Python error classes

Activation-layer failures surface as a small hierarchy. Catch the base class to handle any of them, or a specific subclass to react to one cause.

import blazerules

engine = blazerules.RuleEngine()
try:
    engine.load_rules("rules.yaml")
except blazerules.BlazeRulesParseError as e:
    print("rule file did not parse:", e)
except blazerules.BlazeRulesSchemaError as e:
    print("schema/type problem:", e)
except blazerules.BlazeRulesError as e:
    print("activation failed:", e)

Symptom → meaning → fix

Related documentation