Provider errors

When an agent fails at the provider boundary, the cause is almost always one of six things: a missing SDK extra, a missing credential, a wrong model name, a rate limit, a Vertex AI or Bedrock setup gap, or a timeout. This page maps each error to its fix, verified against the 10xGraph client factory.

Fix a missing SDK extra

The 10xgraph base package does not install any LLM SDK. Each provider is an optional extra, and the client factory raises ImportError with the install command when the SDK is absent.

Install several at once with one command:

# Install the OpenAI, Gemini and Anthropic SDKs together
pip install "10xgraph[openai,google-genai,anthropic]"

Check the install by building an agent. The client is created in the constructor, so a missing SDK fails here rather than at the first request.

from tenxgraph.core import Agent

# Raises ImportError immediately if the OpenAI SDK is not installed
agent = Agent(
    model="gpt-4o",
    system_prompt=[{"role": "system", "content": "You are helpful."}],
)
print("SDK found, provider:", agent.provider)

Fix authentication and API key errors

Each provider reads its key from an environment variable. If the key is missing or wrong, the provider rejects the request, except for Google, where 10xGraph raises a ValueError at construction time.

Export the key in your shell, or load it from a .env file before you build the agent:

from dotenv import load_dotenv

# Reads OPENAI_API_KEY, GEMINI_API_KEY or ANTHROPIC_API_KEY from .env
load_dotenv()

export OPENAI_API_KEY="sk-..."
export GEMINI_API_KEY="your-key"
export ANTHROPIC_API_KEY="sk-ant-..."

You can also pass api_key="..." to Agent for a single agent. Prefer environment variables so keys stay out of source control. If an error persists, confirm the key belongs to the same provider as the model, since gpt-*, gemini-* and claude-* names are routed to different SDKs.

Fix model name and access errors

A “model not found” error means the provider does not recognize the id, or your account cannot use it. 10xGraph picks the provider from the model name, so a typo can also route the request to the wrong SDK.

Provider detection follows these rules:

If the auto-detected provider is wrong, set it explicitly with provider="openai", "google" or "anthropic". Then check the id against the provider’s model list, and confirm that your account tier has access to it. Model ids change over time, so always copy the current one from the provider docs. See Models and providers for how selection works.

Handle rate limits and transient errors

Rate limit responses (HTTP 429) are temporary. Agent already retries them: retry_config defaults to True, which applies the default RetryConfig with exponential backoff.

The default retryable status codes are 429, 500, 502, 503 and 529. Tune the behavior with RetryConfig:

from tenxgraph.core import Agent
from tenxgraph.core.graph import RetryConfig

# Retry up to 5 times, waiting 2s, 4s, 8s, ... capped at 60s
agent = Agent(
    model="gpt-4o",
    system_prompt=[{"role": "system", "content": "You are helpful."}],
    retry_config=RetryConfig(max_retries=5, initial_delay=2.0, max_delay=60.0),
)

If retries are exhausted, you are likely over your quota or tier limit. Reduce concurrency, move bulk work to batch LLM calls, or raise your account tier. Pass retry_config=False only if you want failures to surface immediately.

Configure Vertex AI

Gemini on Vertex AI uses Application Default Credentials and a GCP project instead of an API key. Enable it with use_vertex_ai=True, or by setting GOOGLE_GENAI_USE_VERTEXAI=true.

from tenxgraph.core import Agent

# Requires GOOGLE_CLOUD_PROJECT and Application Default Credentials
agent = Agent(
    model="gemini-2.5-flash",
    use_vertex_ai=True,
    system_prompt=[{"role": "system", "content": "You are helpful."}],
)

For a 403 PermissionDenied, grant the service account a role that allows Vertex AI predictions (roles/aiplatform.user is the usual choice) and enable the API:

# Enable the Vertex AI API on the project
gcloud services enable aiplatform.googleapis.com --project=PROJECT_ID

# Confirm Application Default Credentials resolve
gcloud auth application-default print-access-token

Claude models also run on Vertex AI, but you select that with anthropic_backend="vertex", not use_vertex_ai. Claude model names always route to the Anthropic provider.

Configure Claude on Vertex AI or Bedrock

Anthropic reaches three backends, chosen with anthropic_backend: None for the direct API, "vertex", or "bedrock". Any other value raises ValueError: Unsupported anthropic_backend.

from tenxgraph.core import Agent

prompt = [{"role": "system", "content": "You are helpful."}]

# Vertex AI: the SDK resolves project and region from the environment
vertex_agent = Agent(model="claude-opus-5", anthropic_backend="vertex", system_prompt=prompt)

# Bedrock: keep the anthropic. prefix on the model id
bedrock_agent = Agent(
    model="anthropic.claude-opus-5",
    anthropic_backend="bedrock",
    system_prompt=prompt,
)

10xGraph resolves region, project and AWS credentials through the Anthropic SDK unless you pass them in llm_kwargs. The accepted keys are region, project_id, access_token and credentials for Vertex, and aws_access_key, aws_secret_key, aws_session_token, aws_region, aws_profile and api_key for Bedrock. For example, Agent(..., anthropic_backend="bedrock", aws_region="us-west-2", aws_profile="default").

For a Bedrock ValidationException, check that the model id keeps its anthropic. prefix, that the model is enabled for your AWS account in the chosen region, and that the IAM identity may invoke it. For authentication failures, confirm the AWS profile or credentials resolve outside 10xGraph first.

Fix timeouts and slow responses

Every LLM client is built with a request timeout of 600 seconds. If a call exceeds it, the request fails; raise the limit when you use slow models or long outputs.

The timeout is resolved in this order, first match wins:

1. A value set with set_default_llm_timeout(seconds) from tenxgraph.core.llm.client_factory.
2. The AGENTFLOW_LLM_TIMEOUT environment variable, in seconds. Invalid or non-positive values are ignored with a warning.
3. The built-in default of 600 seconds.

# Allow up to 30 minutes per request
export AGENTFLOW_LLM_TIMEOUT=1800

For OpenAI and Anthropic you can also pass timeout to a single agent, which overrides the default for that client:

from tenxgraph.core import Agent

# timeout is forwarded to the SDK client constructor (seconds)
agent = Agent(
    model="gpt-4o",
    system_prompt=[{"role": "system", "content": "You are helpful."}],
    timeout=1800,
)

The Google client always uses the global default, so use the environment variable or set_default_llm_timeout for Gemini. If calls are consistently slow, try a smaller model, shorten the prompt, or stream the response so users see output earlier.

Related pages

• Models and providers explains provider selection and capabilities.
• Anthropic, Google and OpenAI cover each provider in depth.
• Troubleshooting installation covers package install problems.