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 'agent' or 'completion_model' on a client

error[E0599]: no method named `agent` found for struct `OpenAI` in the current scope

Cause: clients build models, and agents are built from a model. A client has no agent(..) method, and its completion-model method is completion(..).

Fix: build the model from the client, then pass it to AgentBuilder:

use rig::prelude::*;
use rig::providers::openai::{self, OpenAI};

let agent = AgentBuilder::new(OpenAI::from_env()?.completion(openai::GPT_5_5))
    .preamble("You are a helpful assistant.")
    .build();

Tip

use rig::prelude::*; brings in AgentBuilder, Message, and the other everyday types.

cannot find attribute 'tokio' / main is not async

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

Cause: Rig is async, so main needs a runtime, and #[tokio::main] needs Tokio’s macro and runtime features.

Fix: enable them when adding Tokio:

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

API key not set at runtime

Error: environment variable `OPENAI_API_KEY` is not set or is invalid

Cause: from_env() reads the provider’s key from the environment and returns an error 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’s variable is listed in Providers & Clients.

export OPENAI_API_KEY="sk-..."

reached the max turns limit of 1

Cause: an agent makes one model call per prompt by default. Calling a tool and then answering takes at least two: one that requests the tool, one that answers with its result.

Fix: raise the budget, per agent or per prompt. The budget is the total number of model calls the run may make.

let agent = AgentBuilder::new(model).default_max_turns(5).build();

// or for one prompt
let answer = agent.prompt("What is 2 + 2, then times 3?").max_turns(5).await?;

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 description() that says exactly when to use it, and keep the toolset small and non-overlapping. Make sure the turn budget leaves room for the tool call (see above). Confirm the wiring with a mock model that scripts a tool-call turn.

Structured output fails to deserialize

Cause: the model returned JSON that doesn’t match your type. The error is StructuredOutputError::Deserialization, which keeps the model’s raw output so you can inspect it. Usually the schema is ambiguous or a field isn’t clearly described.

Fix: make fields self-describing (doc comments become schema descriptions), use 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.

... is not supported by ... model before the request is sent

Error: RequestError: `reasoning` is not supported by anthropic model `claude-haiku-4-5`: ...

Cause: you set a generation option (reasoning, cache, service tier, …) or provider option that the chosen provider or model can’t honour. Rig refuses the request instead of dropping the option silently.

Fix: remove the option for that model, or add .on_unsupported(OnUnsupported::Ignore) to skip unsupported options with a warning. See Completions.

The run fails on an unknown finish reason

Cause: the provider ended the turn with a finish reason outside Rig’s normalized set (or filtered the content). An agent treats such a turn as failed rather than returning a possibly incomplete answer.

Fix: if that provider’s extra reasons are normal for your use, opt in with .accept_unknown_finish_reasons(true) on the agent builder, the prompt, or the request.

TLS handshake errors behind a corporate proxy

Cause: Rig uses rustls by default, which doesn’t read the operating system’s certificate store. A TLS-inspecting proxy or a private CA then fails the handshake.

Fix: switch to the platform TLS stack:

rig = { version = "0.44.0", default-features = false, features = ["agent", "derive", "reqwest", "native-tls"] }

Feature-gated module doesn’t resolve

error[E0432]: unresolved import `rig::qdrant`

Cause: integrations and some capabilities (vector stores, MCP, PDF and EPUB loaders, image and audio models) are behind cargo features.

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

rig = { version = "0.44.0", features = ["qdrant", "pdf", "image"] }

See Installation for the full list.

Note

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