Troubleshooting

A symptom-to-fix reference for the errors new Rig users hit most. Match the compiler or runtime message to a heading below.

no method named 'from_env' / no method named 'agent' found

error[E0599]: no function or associated item named `from_env` found
   for struct `Client<...>` in the current scope

Cause: these are trait methods, and the trait isn’t in scope. This is the single most common Rig gotcha.

Fix: import the client traits. ProviderClient provides from_env, CompletionClient provides .agent()/.completion_model(), and EmbeddingsClient provides .embedding_model():

use rig::client::{CompletionClient, EmbeddingsClient, ProviderClient};

Tip

Importing use rig::prelude::*; brings all of these traits in at once.

cannot find attribute 'tokio' / main is not async

error: the `async` keyword is missing from the function declaration

Cause: Rig is async, so main must run on a Tokio runtime, and the #[tokio::main] macro needs the right Tokio features.

Fix: enable them when adding Tokio:

cargo add tokio --features macros,rt-multi-thread

OPENAI_API_KEY (or similar) not set at runtime

Error: ProviderError: no API key found in environment

Cause: Client::from_env() reads the provider’s key from the environment and returns Err when it’s missing. It compiles fine — the failure is at runtime.

Fix: export the key (or load a .env file) before running. Each provider documents its variable on its integration page.

export OPENAI_API_KEY="sk-..."

My tool is never called

Cause: the model decides when to call a tool from its name and description. Vague metadata, or too many overlapping tools, makes the model skip it.

Fix: give the tool a clear NAME and a definition() description that says exactly when to use it, and keep the toolset small and non-overlapping. Confirm the wiring in a test by scripting a tool-call turn. If the model loops calling tools forever, you’ll get a MaxTurnsError — see Error handling.

Structured extraction fails to deserialize

Error: JsonError: missing field `category` at line 1 column 42

Cause: the model returned JSON that doesn’t match your struct. Usually the schema is ambiguous or a field isn’t clearly described.

Fix: make fields self-describing (doc comments become schema descriptions), prefer Option<T> for values the model may omit, and use an enum for fixed choices so the model can’t invent a value. See Structured Output.

Streaming / feature-gated APIs don’t resolve

error[E0432]: unresolved import `rig::streaming::StreamingPrompt`

Cause: some capabilities live behind Cargo features (audio, image, PDF/EPUB loaders, MCP).

Fix: enable the feature you need on rig, e.g.:

rig = { version = "0.39.0", features = ["pdf", "audio", "image"] }

Note

Still stuck? Ask in the Rig Discord or open an issue on GitHub. Include the full compiler error and your rig version.