Error reference

Every Weaveflow error carries a stable code, a plain-language message, and a link back to the matching section on this page (NFR-034). Errors render as:

[WEAVEFLOW_SCHEMA_INVALID] <message> (<detail>). See https://github.com/TheDeveloperDoctor/weaveflow/blob/main/docs/errors.md#weaveflow_schema_invalid

All Weaveflow errors subclass WeaveflowError, so a single except WeaveflowError catches every case below. Each error also exposes .code, .message, .detail, and .docs_url.

WEAVEFLOW_SCHEMA_INVALID

A payload did not satisfy a port schema.

Common causes: the value's DataType does not match the port's declared type, or a required field is missing from a structured_json payload.

Fix: check the producing agent's output port against the consuming agent's input port. If the types are merely compatible (not identical), a transform is auto-injected. See Connections & Pipelines.

WEAVEFLOW_CONNECTION_INCOMPATIBLE

Two agents cannot be connected: their ports are incompatible and no transform exists to bridge them.

Fix: make the upstream output type compatible with the downstream input type, or register a transform for the pair. The compatibility graph is documented in Connections & Pipelines.

WEAVEFLOW_ADAPTER_ERROR

An LLM adapter failed at runtime or is misconfigured.

Common causes: a missing API key env var, an invalid provider:model string, or an upstream provider error after retries are exhausted.

Fix: confirm the matching API key is set (OPENAI_API_KEY, ANTHROPIC_API_KEY, …) and the model id is valid for the provider. See LLM Providers.

WEAVEFLOW_ADAPTER_NOT_INSTALLED

The provider SDK is not installed in the current environment.

Fix: install the matching extra, e.g. pip install "weaveflow[anthropic]". The core ships with zero runtime dependencies; each provider's SDK is an optional extra.

WEAVEFLOW_UNKNOWN_PROVIDER

No adapter is registered for the requested provider prefix.

Fix: use one of the registered providers (openai, anthropic, google, mistral, ollama, deepseek) in your "provider:model" string. To add your own, register it in weaveflow/llm/adapters/__init__.py (the registry is the single source of truth for available providers).

WEAVEFLOW_AGENT_EXECUTION

An agent raised an exception during execution.

Fix: inspect .detail for the originating error. Wrap fallible work in guardrail on_error hooks if you need graceful recovery. See Guardrails.

WEAVEFLOW_GUARDRAIL_REJECTED

A guardrail hook rejected the payload (pre or post).

Fix: the payload violated a policy you registered. Inspect .detail for which guardrail rejected it and why. See Guardrails.

WEAVEFLOW_UNKNOWN

The fallback code for a WeaveflowError raised without a more specific subclass. You should rarely see this; if you do, it usually indicates an internal error worth reporting on the issue tracker.