Errors

The client evaluation API never throws. Abnormal execution returns the caller-supplied default with reason: ERROR and an error kind. If a typed getter raised, that is a bug. First diagnostic step: read details, not just the value.

const d = await fireweave.controlPoints.getBooleanDetails('new-checkout', false, ctx);
// d.reason, d.errorKind, d.errorCode, d.errorMessage, d.metadata['fireweave.errorKind']

errorKind (also copied onto metadata['fireweave.errorKind']) is the Fireweave kind. Use it to tell NotReady from AlreadyClosed — both still carry the historical OpenFeature code PROVIDER_NOT_READY on errorCode. The bundled OpenFeature provider is gone; the codes remain on the Decision because spec/errors.schema.json pins them.

15 kinds

Canonical kinds from contracts/errors.md / spec/errors.schema.json. Messages are secret-redacted (no API keys, bearer tokens, or FW_PROJECT_API_KEY values).

Kind	Envelope `errorCode`	Retryable	When
`NotReady`	`PROVIDER_NOT_READY`	yes	Evaluation before successful init
`FlagNotFound`	`FLAG_NOT_FOUND`	no	Key absent (includes quota-empty snapshots → default + `fireweave.quotaLimited: true`)
`TypeMismatch`	`TYPE_MISMATCH`	no	Stored type ≠ requested getter
`InvalidContext`	`INVALID_CONTEXT` or `TARGETING_KEY_MISSING`	no	Bad/oversized context; missing targeting key when required
`Authentication`	`GENERAL`	no	HTTP 401 / invalid key
`Authorization`	`GENERAL`	no	HTTP 403 / key lacks permission
`RateLimited`	`GENERAL`	yes	HTTP 429 (still serve defaults)
`Timeout`	`GENERAL`	yes	Request or init deadline exceeded
`Network`	`GENERAL`	yes	DNS / connect / reset / TLS
`BackendUnavailable`	`GENERAL`	yes	5xx / upstream unavailable
`MalformedResponse`	`PARSE_ERROR`	no	Non-JSON or schema-invalid body
`UnsupportedCapability`	`GENERAL`	no	Adapter lacks the operation (InMemory `registerTarget`)
`Configuration`	`PROVIDER_FATAL` (init) / `GENERAL` (runtime)	no	Invalid host, missing required key or `mode`, bad options
`AlreadyClosed`	`PROVIDER_NOT_READY`	no	Call after shutdown
`Internal`	`GENERAL`	no	Unexpected invariant

* MalformedResponse is permanent for a given response; a later request may succeed. Adapters must not invent flag values. InvalidContext subtype: missing required targetingKey → TARGETING_KEY_MISSING. All other context violations (type, reserved keys, size/depth/count bounds) → INVALID_CONTEXT. Init is the exception to never-throw: bad mode or credentials raise Configuration at boot. See Lifecycle.

Language surfaces

Language	Type
Node / Web	Single class `FireweaveError` with `kind`, `openFeatureErrorCode`, `retryable`
Python	`ErrorKind` plus subclasses (`NotReadyError`, `FlagNotFoundError`, `TimeoutError_`, `TargetingKeyMissingError`, …)
Go	`fireweave.Error` with `ErrorKind` constants; implements `error`. Evaluate still does not return `error`
Java	`ErrorKind` enum + `FireweaveException` / `FireweaveError` value type. Evaluation returns defaults
Rust	`FireweaveError` — `init_fireweave` returns `Result`; reads never panic
Swift	`FireweaveError` — `initFireweave` throws; reads never throw

Reasons that are not errors

`reason`	Meaning
`TARGETING_MATCH`	Conditions matched
`SPLIT`	Backend reported percentage-rollout bucketing
`DISABLED`	Control point exists and is off — you get the off/default value
`STATIC`	Local adapter hit in the seeded map
`DEFAULT`	Local adapter: unknown key (not `FlagNotFound`)
`STALE`	Last-good or timed-out prefetch (web / Swift boot ceiling). Check `fireweave.fromCache` when present
`CACHED`	Served from a fresh cache
`ERROR`	Inspect the error kind

`UnsupportedCapability`

Expected in v1 for:

InMemoryAdapter.registerTarget — the fixture adapter does not persist registration. Use mode: 'local' when the test needs to assert it.
A custom adapter that does not implement register.

The guardrails stub is gone. client.guardrails is a compile/import error, not an UnsupportedCapability result. Guardrails are platform-managed; the SDK has no guardrails API.

Troubleshooting

Default values, auth, STALE

Control points

Never-throw reads and Decision reasons

Get Started

SDKs

Concepts

Production

CLI

Terraform

Testing

Troubleshooting

Migration

Reference

15 kinds

Language surfaces

Reasons that are not errors

`UnsupportedCapability`

Next

Troubleshooting

Control points

​15 kinds

​Language surfaces

​Reasons that are not errors

​UnsupportedCapability

​Next

Troubleshooting

Control points

15 kinds

Language surfaces

Reasons that are not errors

`UnsupportedCapability`

Next