Errors¶

Every failure bloomery raises derives from BloomeryError — one except BloomeryError catches everything — and every class lives in bloomery.errors, importable without pulling in any pipeline stage.

The hierarchy¶

BloomeryError
├── InvariantViolated
├── SpecParseError
├── UnknownTransformError
├── TypeCheckError
├── TransformRegistrationError
├── StepError
│   ├── StepDeterminismError
│   └── StepContractViolation
├── ResolutionError
│   ├── CircularDerivation
│   └── MissingReference
├── GuardrailError
│   ├── UnitMismatch
│   ├── TaxBasisMismatch
│   ├── CurrencyMismatch
│   ├── GrainMismatch
│   ├── AdditivityViolation
│   ├── AssertLoweringError
│   ├── GrainViolation
│   ├── FanoutRisk
│   ├── HistoricalFanout
│   ├── NonAdditiveWithoutComponents
│   ├── FalseAdditivityClaim
│   ├── InvalidMetricShape
│   ├── MetricFilterInvalid
│   ├── MartMissingTimeDimension
│   ├── UnprovableRollup
│   ├── ReservedEntityName
│   ├── DanglingExposure
│   ├── DanglingExport
│   ├── UnexportedImport
│   ├── UnknownUpstream
│   ├── ImportCollision
│   ├── ImportCycle
│   ├── NamelessImporter
│   ├── UndeclaredZone
│   ├── UndeclaredRatioRows
│   ├── RatioOperandsDisagree
│   ├── QuarantineRetentionMissing
│   ├── DedupeTieBreakMissing
│   ├── DedupeDispositionConflict
│   ├── IngestionMetadataMissing
│   ├── RedactionConflict
│   ├── SecretPublished
│   └── AudienceWidened
├── PlanError
│   ├── ContractViolation
│   └── RenameTargetMissing
├── EmitError
│   └── UnsupportedByTarget
├── ArtifactImportError
└── PlannerError
    ├── UnknownMember
    ├── UnreachableAtGrain
    ├── AmbiguousDimension
    ├── InvalidRequest
    ├── FilterTypeMismatch
    └── UnsupportedFilter
        ├── UnsupportedSetRelation
        ├── UnsupportedHierarchy
        ├── UnsupportedTextOperator
        ├── FilterTooComplex
        ├── UnsupportedNegation
        ├── InvalidLiteral
        ├── UnsupportedSortNulls
        ├── UnsupportedPagination
        ├── UnsupportedFieldCompare   (adapter-owned)
        └── UnsupportedQuantifier     (adapter-owned)

Per class¶

Data-quality refusals without their own class¶

Five data-quality guardrails have named leaves (above). The rest raise a bare GuardrailError — the design authority names five, and minting further classes would put names in bloomery.errors no RFC has decided on. Each is still a distinct, addressed message inside the same batched aggregate:

Data-quality refusals also happen at emit time rather than compile time, and those are UnsupportedByTarget. Two are about the dialect, both on an absent NULL-on-failure cast: an entity with coercible rules (S-0033/D-30), and — because the ingestion-metadata audit asserts _ingested_at casts to timestamp, which is a TRY_CAST of its own — a dedupe-only entity too, even though it carries no quality rules at all (D31). A third is about an absent Unicode normalization (D86). None of the three can fire on a shipped dialect: DuckDB and Trino have TRY_CAST, Postgres gets a guard around its own input parser (D84), and all three normalize. They are what a fourth dialect would meet if it arrived without the capability, and they are provoked in the test suite against exactly such a dialect.

A fourth is about a target's mechanism rather than its SQL: a grants: block is refused for Cube, because Cube reads relations it does not own and so has nothing to apply a grant with. Emitting it anyway would put a restriction in a file that restricts nothing, and dropping it silently would let a project believe a restriction it declared is in force on every target it compiles for.

None is about a target's artifact families any more. A quarantine: block and a reconcile: check were refused for dbt until it grew the reject table, the replay macro and the comparison model; what dbt still refuses is a Tier 3 python_model step, which is about the adapters dbt's Python models run on rather than about anything bloomery lowers. All of them name the target or dialect that does support the construct.

Retrieval refusals¶

A retrieval document declares a surface over relations the project already builds, and seven guardrails make that declaration mean something. All seven raise RetrievalViolation, a GuardrailError subclass that lives in bloomery.guardrails.retrieval rather than in bloomery.errors — retrieval ships as its own spec kind, nothing outside that module raises the class, and promoting it into the exported taxonomy is a decision no design authority has taken. Catching GuardrailError catches all of it, and every one arrives inside the same batched aggregate, addressed retrieval: profiles.<name>.

Every disagreement is reported, not the first. A profile is authored as one block and is usually got wrong in more than one way at once — a space renamed, its dimensions bumped and a column dropped are one edit, and reporting them one at a time would be three round trips.

An eighth refusal is about the relation rather than the profile: a profile naming an entity or a mart this project does not build declares a surface nothing can serve, and every other check on it has nothing to read. It reports the relation and stops there rather than cascading six more leaves off one missing name — which is also what a mart that failed its own check looks like from here, one leaf in the same batch beside the mart's own.

What is not here: anything about a vector store, an index, or whether an encoder model exists. A declared vector is also not a column a warehouse port emits DDL for, so compiling a vector-carrying relation for a SQL target is an UnsupportedByTarget ("no physical type for vector(float32, 1536)") rather than a retrieval refusal — the relation is written by the platform's step, and what bloomery contributes is the contract for querying it. See Retrieval.

The closed refusal list¶

The UnsupportedFilter family is a closed, reviewed list (S-0032), not drift: every construct the query vocabulary cannot express was refused deliberately, with a named error and a rationale. The stable .reason codes raisable by bloomery's three parse functions (parse_filter_json, parse_sort_json, parse_page_json) are exported as bloomery.planner.KNOWN_UNSUPPORTED and drift-guarded by test — adapters key their refusal handling (HTTP problem responses, UI messages) on .reason, and assert their own refusal sets against the export. Anything not on the list must translate; growing the list is a reviewed decision, never an accident.

A refusal is not the same thing as malformed input. The parse functions raise UnsupportedFilter only for constructs the vocabulary reviewed and declined (some during tree construction, some after the rewrite — see the API reference) — a document that is simply ill-formed (a non-mapping payload, a field map of the wrong shape, an unknown $op, an operand of the wrong type, a nulls value that is neither "first" nor "last", a non-int limit) raises InvalidRequest and never carries a .reason from the closed list. Handle the two separately: a .reason is a product decision to surface, an InvalidRequest is a caller bug to fix.

Fix suggestions¶

Five refusals carry a structured next action beside the prose, because a human reads a message and a program reads a structure. Each field exposes a value bloomery already computed on its way to writing the message:

MartCoverage(mart, metric, grain) and MeasureRef(measure, grain) are frozen public dataclasses, exported from the package root. They are typed values rather than encoded strings on purpose: a tuple[str, ...] could name the marts but not say which metric each covers at which grain, and that pairing is the whole content of the conflict.

from bloomery.errors import UnreachableAtGrain

try:
    planner.plan(ir, request, dialect="duckdb")
except UnreachableAtGrain as refusal:
    for entry in refusal.covering_marts:
        print(f"{entry.metric} lives on {entry.mart} at grain {entry.grain}")

A dimension another mart carries¶

Asking for a dimension the serving mart does not flatten used to refuse as UnknownMember with a guess at the nearest column name. That is false whenever the dimension exists on another mart: it sends you to declare something already declared. Those requests now refuse as UnreachableAtGrain, and refusal_reason answers the only question that changes what you do next.

"not_flattened" means the rollup to that dimension's grain is provable and the mart simply does not carry the column — one line of spec fixes it, and the message names the line:

dimension 'region' is not on mart 'order_items', which serves this request; mart 'orders'
carries it at grain 'order'.
  Values at 'order_item' roll up to 'order' safely, so the column can be flattened onto
  this mart at build time: add `flatten: {via: item_of_order}` to mart 'order_items'.

Any other value is a RefusalReason — the rollup itself does not hold, and that member names which repair applies:

from bloomery.errors import UnreachableAtGrain
from bloomery.semantic import RefusalReason

try:
    planner.plan(ir, request, dialect="duckdb")
except UnreachableAtGrain as refusal:
    if refusal.refusal_reason == "not_flattened":
        ...  # the message names the mart and the flatten to add
    elif refusal.refusal_reason:
        reason = RefusalReason(refusal.refusal_reason)

The same diagnosis reaches a filter or a row policy naming such a column: all three resolve the dimension through one function, and a filter on a column another mart carries has the same cause and the same repair as a group-by does.

bloomery never joins at plan time, in either case. The join belongs to the mart, where it is proven once when the mart is built rather than re-decided on every request — so the repair is always a spec edit, never a flag on the query.

Absence has one representation, and "the attribute is missing" is not it. Every field is always present: a collection field is () and a scalar is None when there is nothing to suggest, so no caller needs getattr. An empty suggestion is a fact rather than a search that was skipped, and the two emptinesses mean different repairs — covering_marts == () means no mart lists the metric at all (define one), while a populated tuple means the metrics are split across grains (request them separately).

Nothing is fabricated. $empty is refused because eq "" and is_null true are different questions, so nearest_supported is None there and the message names both; a set relation has no scalar counterpart at all. And nothing is discoverable only through a suggestion — the primary contract stays the message and, for UnsupportedFilter, the .reason code.

nearest_supported is the Op value rather than the member, because bloomery.errors imports nothing. Op is a StrEnum, so refusal.nearest_supported == Op.LIKE holds and Op(refusal.nearest_supported) round-trips.

Advisories are not errors¶

Some findings are worth saying and not worth refusing over. Those are advisories: evaluate() returns them on SpecEvidence.advisories, sorted and deduplicated, and no exception is raised. They are a separate channel from the hierarchy above — nothing here is ever raised, and nothing above is ever reported as an advisory.

The bar is deliberately high, and it is the same sentence in three parts: the spec is legal, the compiled artifacts are correct, and there is still something you would want to know. Anything where the numbers could be wrong stays a refusal. bloomery does not soften "refuse rather than answer wrongly", and an advisory standing where a refusal belongs is a defect in bloomery, not a convenience.

Branch on code, never on the message: the vocabulary below is a closed, reviewed list and each addition is a change someone signed off, while message text is prose that improves between releases.

Advisories carry a source_path under the same rules as an error's, below.

Two channels advisories are deliberately not:

• Log records. bloomery emits nothing at WARNING — that severity belongs here, and a finding that was only logged is a finding a caller who configured no handler never received. See stability for the logger hierarchy.
• DeprecationWarning. A spelling on its way out is announced through Python's warnings module under BloomeryDeprecationWarning, so a suite run with -W error sees it. That is a statement about the library's surface; an advisory is a statement about your spec.

source_path¶

Every error carries an optional source_path — a dotted/bracketed address into the authored document, prefixed with the document's name (the key you passed to load_project, or a deterministic label like mapping[shop__orders->order] where parsed models no longer know their file):

mappings/shopify.yaml: fields.unit_price.from

The parse stage always sets it; later stages set it best-effort.

Batching¶

The parse, resolution, and guardrail stages batch: they collect every individual failure in the stage and raise one aggregate whose message lists every path, so a spec is fixed in one round-trip rather than one error at a time. On an aggregate, exc.collected holds the individual errors as a tuple for machine consumption; BloomeryError.from_collected(errors) is the constructor that builds one. A stage with a single failure raises that failure directly, uncollected.

Planner errors are deliberately not batched — a request fails on its first problem, because request-time callers want one actionable refusal, not a report.