Errors¶

Only these errors cross a public boundary (RULES C5). Each has a stable code, and to_info() gives its serializable ErrorInfo. Outcomes and errors explains the taxonomy.

The HarnessWeaver error taxonomy (RULES C5). See harnessweaver.core.errors.

BoundViolation ¶

BoundViolation(message: str, **details: JsonValue)

Bases: SpecError

A value is outside the bounds the org baseline set (R10).

BudgetExceeded ¶

BudgetExceeded(message: str, **details: JsonValue)

Bases: HarnessError

A run would exceed, or has exceeded, one of its budget limits.

DeadlineExceeded ¶

DeadlineExceeded(message: str, **details: JsonValue)

Bases: HarnessError

A run passed its deadline.

ErrorCode ¶

Bases: StrEnum

Stable, language-neutral error codes.

ErrorInfo ¶

Bases: BaseModel

The serializable form of an error, as carried by hook events and the wire API.

ExpressionError ¶

ExpressionError(message: str, **details: JsonValue)

Bases: HarnessError

A cel-lite expression could not be compiled or evaluated.

ExpressionEvalError ¶

ExpressionEvalError(message: str, **details: JsonValue)

Bases: ExpressionError

A cel-lite expression failed at evaluation time (missing key, type mismatch, ...).

ExpressionSyntaxError ¶

ExpressionSyntaxError(message: str, **details: JsonValue)

Bases: ExpressionError

A cel-lite expression is malformed or calls something that doesn't exist.

HarnessError ¶

HarnessError(message: str, **details: JsonValue)

Bases: Exception

Base class for every error HarnessWeaver raises across a public boundary.

to_info ¶

to_info() -> ErrorInfo

Return the serializable form of this error.

IncompatibleContract ¶

IncompatibleContract(message: str, **details: JsonValue)

Bases: SpecError

A plugin was built for a contract range this core doesn't support (V5).

InternalError ¶

InternalError(message: str, **details: JsonValue)

Bases: HarnessError

A bug or an unexpected failure inside HarnessWeaver or a plugin.

LevelTooLow ¶

LevelTooLow(message: str, **details: JsonValue)

Bases: SpecError

The app's effective spec is below the adoption level its risk tier requires.

LockViolation ¶

LockViolation(message: str, **details: JsonValue)

Bases: SpecError

A later layer changed a value the org baseline locked (R1).

ModelRefusal ¶

ModelRefusal(
    message: str = "the model declined the request",
    *,
    response: ModelResponse | None = None,
    **details: JsonValue,
)

Bases: RunBlocked

The model declined the request, or a content filter cut its answer short.

Providers raise this, with the code model_refusal, instead of returning the answer. A declined call still costs tokens, so response carries its usage and cost for the run to count, without its text (R9).

Parameters:

Name	Type	Description	Default
`message`	`str`	Never the model's own words (R9).	`'the model declined the request'`
`response`	`ModelResponse \| None`	What the call used. Leave its text empty.	`None`
`**details`	`JsonValue`	Extra details, such as the refusal's `category`.	`{}`

NotFound ¶

NotFound(message: str, **details: JsonValue)

Bases: HarnessError

A run, approval or other named thing doesn't exist.

PluginConflict ¶

PluginConflict(message: str, **details: JsonValue)

Bases: SpecError

Two installed plugins claim the same namespace.

PluginNotAllowed ¶

PluginNotAllowed(message: str, **details: JsonValue)

Bases: SpecError

A spec uses a plugin that the org baseline's plugins.allow list excludes.

PolicyDenied ¶

PolicyDenied(message: str, **details: JsonValue)

Bases: HarnessError

A deterministic policy refused an action.

ProviderError ¶

ProviderError(message: str, **details: JsonValue)

Bases: HarnessError

A model or other upstream provider failed. Usually worth retrying.

RunBlocked ¶

RunBlocked(message: str, **details: JsonValue)

Bases: RunInterrupted

A hook refused the step. details["code"] holds the Block code.

RunEscalated ¶

RunEscalated(message: str, **details: JsonValue)

Bases: RunInterrupted

A hook handed the run to a human queue.

RunInterrupted ¶

RunInterrupted(message: str, **details: JsonValue)

Bases: HarnessError

A hook stopped the run with Block, Escalate or Suspend (ADR-0020).

In run style the harness turns these into the run's status. In session style they are raised to the app's code, which may catch them.

RunSuspended ¶

RunSuspended(message: str, **details: JsonValue)

Bases: RunInterrupted

A hook paused the run until an approver answers.

SpecError ¶

SpecError(message: str, **details: JsonValue)

Bases: HarnessError

A spec is invalid. Raised when a harness loads, never at run time.

ToolError ¶

ToolError(message: str, **details: JsonValue)

Bases: HarnessError

A tool failed while executing.

UnknownProvider ¶

UnknownProvider(message: str, **details: JsonValue)

Bases: SpecError

A spec names a provider, runner or plugin that isn't installed (R4).

UnreachableHook ¶

UnreachableHook(message: str, **details: JsonValue)

Bases: SpecError

A runner or adapter can't reach a hook point the baseline needs (R4).

ValidationFailed ¶

ValidationFailed(message: str, **details: JsonValue)

Bases: HarnessError

Input or output failed validation and could not be repaired.

classify ¶

classify(exc: BaseException) -> HarnessError

Translate any exception into the taxonomy, defaulting to InternalError.

from_known ¶

from_known(exc: BaseException) -> HarnessError | None

Translate a well-known exception into the taxonomy, or return None.

Adapters call this first and fall back to InternalError.