Initialize, ready, shutdown

One state machine in every language:

UNINITIALIZED ── init() ──► INITIALIZING ──► READY ◄──recovery──► STALE / ERROR
                                 │                     │
                          fatal config/auth        shutdown()
                                 ▼                     ▼
                               FATAL ─────────────► SHUTDOWN   (idempotent, terminal)

State	Meaning
`UNINITIALIZED`	Constructed, not started
`INITIALIZING`	Config validated, adapter starting
`READY`	Remote: client constructed successfully. Evaluations are live
`STALE`	Last-good / timed-out path. Web and Swift: prefetch lost a 5 s ceiling — reads are defaults with reason `STALE`. Do not collapse this into `READY`
`ERROR`	Transient failure; evaluations degrade to defaults until recovery
`FATAL`	Config or auth failure. Not retried
`SHUTDOWN`	Terminal for that instance. Construct a new runtime

Recommended pattern: one client per process per backend project, created at boot with initFireweave / Init / Fireweave.init, shared, shut down once on exit. There is no OpenFeature provider to register, wait on, or close.

Initialize

mode is required and never inferred. Init order: validate options → construct the matching adapter → adapter init → READY. Configuration and auth failures throw (kind Configuration). Reads on the returned client never throw.

Node
Web
Python
Go
Java

const fireweave = await initFireweave({
  mode: 'remote',
  apiUrl: process.env.FW_API_URL!,
  apiKey: process.env.FW_PROJECT_API_KEY!,
});
// READY (or threw Configuration)

initFireweave awaits runtime.initialize(). There is no lazyReady. Observe runtime.getState() if you construct the runtime yourself.

const fireweave = await initFireweave({
  mode: 'remote',
  apiKey: PUBLIC_FW_PROJECT_API_KEY,
  apiUrl: PUBLIC_FW_API_URL,
  context: { targetingKey: 'anonymous' },
});

A bad host or missing credential still rejects initFireweave() even though FireweaveWebRuntime.initialize() is deliberately fail-open. A hung prefetch must not block app boot.If the prefetch loses the 5 s ceiling (DEFAULT_FLAGS_READY_TIMEOUT_MS), state is STALE, not READY. Values are defaults with reason STALE. That is fail-open, not fail-silent: a timed-out boot is distinguishable from a successful one where every control point happened to be off.

client = init_fireweave(
    mode="remote",
    api_key="project-api-key_...",
    api_url="https://app-server.fireweave.ai",
)

init_fireweave brings the runtime to READY or raises ConfigurationError.

client, err := fireweave.Init(fireweave.Options{
    Mode:   fireweave.ModeRemote,
    APIKey: apiKey,
    APIURL: apiUrl,
})

Concurrent Initialize callers (if you construct the runtime yourself) observe a single adapter initialization.

FireweaveClient client = Fireweave.init(InitOptions.remote(apiKey, apiUrl));

Throws FireweaveException (kind Configuration) on a bad init table row. Observe client.runtime().state().

Wait for a successful initFireweave / Init before treating values as live. On web and Swift, also check that the runtime is not STALE if a zero-ramp and a failed prefetch would look the same to you.

Why `mode` cannot be inferred

With inference, a missing or mistyped credential in production silently became local evaluation. Every control point served its seeded or caller default, nothing raised, and the boot log was green. The observable symptom was a feature that never ramped, indistinguishable from a rollout nobody started. remote without credentials is a boot error. local in production is something a human typed.

Shutdown

Shutdown belongs to the runtime. It is idempotent. Default deadline: 10 s.

Language	Call
Node	`await fireweave.shutdown()` — flushes queued network I/O first
Web	`await fireweave.shutdown()` — flushes, then shuts down. Also `visibilitychange → hidden` and `pagehide` via `keepalive` / `sendBeacon`
Python	`client.shutdown()`
Go	`client.Runtime().Shutdown(ctx)`
Java	`client.close()` (`AutoCloseable`) / `runtime.shutdown()`
Rust	`client.shutdown()`
Swift	`await client.shutdown()`

v1 reads are side-effect free. There is no client exposure queue to drain before close.

Web unload prefers keepalive fetch so it can send Authorization: Bearer. sendBeacon cannot set that header and is a fallback.

After shutdown

Evaluations return defaults with AlreadyClosed.
A shut-down runtime is terminal. initialize() after shutdown fails with AlreadyClosed. Construct a new client.

Concurrency

Runtimes and clients are safe for concurrent evaluation on one instance. Evaluations racing shutdown either complete or observe AlreadyClosed — never a crash.

Configuration and auth

Required mode, credentials, fw_public_

Troubleshooting

Defaults, STALE, AlreadyClosed

Get Started

SDKs

Concepts

Production

CLI

Terraform

Testing

Troubleshooting

Migration

Reference

Initialize, ready, shutdown

Initialize

Why `mode` cannot be inferred

Shutdown

After shutdown

Concurrency

Next

Configuration and auth

Troubleshooting

​Initialize

​Why mode cannot be inferred

​Shutdown

​After shutdown

​Concurrency

​Next

Configuration and auth

Troubleshooting

Initialize

Why `mode` cannot be inferred

Shutdown

After shutdown

Concurrency

Next