How to Configure Multi-Provider Fallback When a Primary Provider Fails in OpenBB

OpenBB supports automatic multi-provider fallback by configuring the PROVIDERS.<service>.FALLBACK list in openbb.yaml or environment variables, allowing the ProviderExecutor to sequentially attempt backup data sources when the primary provider raises an exception.

The OpenBB Platform (OpenBB-finance/OpenBB) provides a robust multi-provider architecture that ensures data availability even when primary sources experience outages. By configuring multi-provider fallback in your OpenBB configuration, you can define automatic failover chains that require no code changes to individual provider implementations.

Understanding the Provider Registry Architecture

OpenBB loads all data providers through the provider registry (openbb_core.provider.registry.RegistryLoader). The registry discovers every provider implementation exposed via entry points and stores them in Registry.providers as defined in openbb_platform/core/openbb_core/provider/registry.py.

When a request executes, the platform resolves the requested provider name (case-insensitive) from this registry. If that provider raises an exception—such as an API outage, quota exceeded, or network error—the framework initiates the fallback sequence.

Configuring Fallback Providers via openbb.yaml

The fallback order is defined in the OpenBB configuration file (openbb.yaml) or through corresponding environment variables. The configuration key follows the pattern PROVIDERS.<service>.FALLBACK, accepting a list of provider names as registered in the registry.

# openbb.yaml (placed in the repository root or $HOME/.openbb)

PROVIDERS:
  EQUITY_PRICE:
    FALLBACK: ["yfinance", "alpha_vantage", "fred"]

For containerized deployments or CI/CD pipelines, use the environment variable format:

export OPENBB_PROVIDERS_EQUITY_PRICE_FALLBACK="yfinance,alpha_vantage,fred"

When executing a command, OpenBB attempts providers in the specified order until one succeeds:

from openbb import openbb as ob

# Request the latest price for AAPL

price = ob.equity.price(ticker="AAPL", provider="yfinance")
print(price)

If yfinance fails, the platform automatically tries alpha_vantage, then fred. If all providers fail, it raises the original error with a clear message including the attempted fallback chain.

Internal Fallback Execution Flow

The fallback mechanism operates within the core query-execution layer through three distinct phases:

1. Registry Loading – RegistryLoader.from_extensions() discovers providers via entry points and populates Registry.providers in openbb_platform/core/openbb_core/provider/registry.py.

2. Provider Selection – The executor resolves the requested provider name from the registry when processing a command.

3. Fallback Loop – The ProviderExecutor (located in openbb_platform/core/openbb_core/app/static/query_executor.py) catches any OpenBBError raised by the primary provider. If a fallback list is configured, it iterates over the provider names, fetching each from the registry in turn. The first successful response is returned; if none succeed, the original error is re-raised from openbb_platform/core/openbb_core/app/static/container.py.

Runtime Programmatic Configuration

You can override fallback configurations dynamically without modifying YAML files. Access the registry directly to adjust fallback orders for specific services:

from openbb_core.provider.registry import RegistryLoader

# Load the registry once

registry = RegistryLoader.from_extensions()

# Override fallback for a specific service

registry.providers["equity_price"].fallback = ["alpha_vantage", "fred", "yfinance"]

The fallback attribute is processed by the executor exactly like the YAML-based configuration, enabling temporary provider prioritization for specific analytical workflows.

Core Source Files and Components

The multi-provider fallback logic spans several key files in the OpenBB core:

• openbb_platform/core/openbb_core/provider/registry.py – Implements RegistryLoader.from_extensions() to discover and register providers via entry points.
• openbb_platform/core/openbb_core/app/static/query_executor.py – Contains ProviderExecutor which executes queries, catches provider errors, and implements the fallback loop.
• openbb_platform/core/openbb_core/app/static/container.py – Raises OpenBBError when no provider (including fallbacks) can satisfy the request.
• openbb_platform/core/openbb_core/env.py – Reads configuration values from openbb.yaml and environment variables (OPENBB_*).

Summary

• Configure fallback chains using PROVIDERS.<service>.FALLBACK in openbb.yaml or OPENBB_PROVIDERS_<service>_FALLBACK environment variables.
• The ProviderExecutor in query_executor.py automatically iterates through fallback providers when the primary source raises an OpenBBError.
• Modify fallback orders programmatically via registry.providers["service_name"].fallback after loading the registry with RegistryLoader.from_extensions().
• No modifications to individual provider code are required to enable failover behavior.

Frequently Asked Questions

What triggers the fallback mechanism for a primary provider?

The fallback mechanism triggers when the primary provider raises an OpenBBError—covering API outages, quota limits, or network failures—during query execution in openbb_platform/core/openbb_core/app/static/query_executor.py. The ProviderExecutor catches this exception and initiates the sequential fallback loop.

Can I use environment variables to configure provider fallback?

Yes. Convert the YAML configuration key to uppercase with underscores: OPENBB_PROVIDERS_EQUITY_PRICE_FALLBACK. Set the value as a comma-separated string of provider names (e.g., "yfinance,alpha_vantage,fred") for Docker, Kubernetes, or shell environments.

Is it possible to modify fallback chains at runtime?

Yes. After loading the registry with RegistryLoader.from_extensions(), you can directly assign a new list to registry.providers["service_name"].fallback. This programmatic override takes effect immediately for subsequent queries without requiring a platform restart.

What error does OpenBB raise when all fallback providers fail?

If all providers in the fallback chain fail, OpenBB re-raises the original OpenBBError from openbb_platform/core/openbb_core/app/static/container.py, including details of the attempted fallback chain in the error message to facilitate debugging.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}