Troubleshoot Runifold applications

Installation and compilation

Symptom	Likely cause	Action
`ProviderModelExt` or `from_api_key` is missing	old `runifold` release	confirm `runifold = "0.9.0"` and run `cargo update -p runifold`
provider module cannot be imported	Cargo feature is disabled	enable `openai`, `anthropic`, `gemini`, `ollama`, or `bedrock`
Tokio main macro is missing	runtime features are absent	enable `tokio/macros` and `tokio/rt-multi-thread`
two Runifold types do not match	mixed crate versions	update all `runifold-*` crates to the same release
compiler is too old	MSRV is not satisfied	Runifold 0.9.0 requires Rust 1.88 or newer

Start diagnosis with:

rustc --version
cargo tree -i runifold
cargo check

Authentication and endpoints

An HTTP 401 usually means a missing, invalid, revoked, or wrong-environment credential. A 403 usually means the identity exists but lacks project, model, region, or organization access. A 404 may mean the model identifier or base URL does not match the selected provider protocol.

Check the credential in the same process environment that launches the application. Never print the secret. Log only whether configuration was present, which provider and model were selected, and the sanitized error category.

Model and capability errors

If a request works as plain text but fails with Tools or structured output:

verify the exact model supports the feature;
inspect Runifold warnings and the full outcome;
confirm the adapter is native or uses the intended compatible wire protocol;
reduce to the smallest request;
run a live smoke test for that model-feature combination.

Do not silently fall back from required structured output or Tool execution to unvalidated text.

Timeouts, retries, and streams

A network timeout bounds one operation. A Run deadline bounds the useful lifetime of the execution tree. Inspect which boundary fired before changing limits.

Do not retry refusals, invalid requests, denied capabilities, exhausted budgets, or ambiguous writes blindly. Runifold retries only when the adapter marks the failure safe, but application retries must preserve the same rule.

For a stream that appears truncated, verify that the consumer reads until a terminal event, handles error events, and does not discard the final usage or outcome. Cancel the Run when the downstream client disconnects.

Workflows, storage, and recovery

Symptom	Check first
workflow resumes an old definition	definition version and checkpoint schema
two Workers execute the same task	lease fencing token and heartbeat expiry
completed Tool runs again after restart	write-ahead effect record and idempotency key
task never wakes	signal name, tenant scope, retention, and timer clock
checkpoint update is rejected	stale revision or compare-and-swap conflict

Ambiguous state is not success. Preserve the record, reconcile against the external system, and apply an explicit resume policy.

Build a useful minimal reproduction

Include:

exact runifold and Rust versions;
enabled Cargo features;
provider and model identifiers without credentials;
the smallest request, Tool schema, or Workflow definition;
sanitized error kind and retry-safety classification;
whether failure occurs in offline tests or only live;
relevant Run and invocation IDs without user content.

First reproduce with a scripted model or cassette. If only the live service fails, add a narrowly budgeted Provider smoke test and compare the wire capability evidence.