Errors and warnings

Typed failures you can catch precisely.

Every Bloomberg, session, validation, and timeout failure is a subclass of BlpError. Diagnostics that should not stop your program, such as delayed data or rejected subscription fields, are ordinary Python warnings.

Hierarchy

Exception
├── BlpError
│   ├── BlpSessionError
│   ├── BlpRequestError
│   │   ├── BlpLimitError
│   │   ├── BlpSecurityError
│   │   ├── BlpFieldError
│   │   └── BlpSubscriptionDataLossError
│   ├── BlpValidationError
│   ├── BlpTimeoutError
│   ├── BlpInternalError
│   └── BlpBPipeError
└── Warning
    └── UserWarning
        └── BlpSubscriptionWarning
            ├── BlpDelayedDataWarning
            └── BlpFieldWarning

Import every class from xbbg (or xbbg.exceptions). BlpError is defined by the native extension, so tracebacks and type(exc).__mro__ show it as xbbg._core.BlpErrorBase. The public BlpRequestError family and BlpValidationError are Python subclasses of native classes of the same name; xbbg converts native errors to them at request, recipe, and subscription boundaries, so except xbbg.BlpRequestError catches every request failure. BlpTimeoutError is not a BlpRequestError: catch it separately or through BlpError.

When each error is raised

Exception	Raised when
BlpError	Base class for everything below; use it as a catch-all
BlpSessionError	A Bloomberg session cannot start, a service cannot be opened, or every request worker has died
BlpRequestError	Bloomberg rejects a request (for example a responseError, or every security failing), on_delayed="raise" finds delayed data, or a subscription request fails
BlpLimitError	Bloomberg answers with a LIMIT category, such as DAILY_CAPACITY_REACHED
BlpSecurityError, BlpFieldError	Reserved for security- and field-level failures; the 1.8.0 engine records partial security and field failures in result metadata and raises BlpRequestError when every security fails
BlpSubscriptionDataLossError	A subscription stream has a continuity gap: Bloomberg DATALOSS, a full drop_newest buffer, or an overflow or timeout of the block forwarder
BlpValidationError	Input is rejected before or by the request planner: missing required parameters, unknown field_types names, an invalid on_delayed value or return_eids/on_delayed on an unsupported operation, invalid enum values, unknown fields under strict validation, schema mismatches, and auction preflight failures
BlpTimeoutError	A request exceeds request_timeout_ms (no timeout by default), or an engine step such as identity authorization or opening a service times out
BlpInternalError	An unexpected engine failure, including engine startup when no Bloomberg session can be reached ("failed to spawn worker 0: session start failed")
BlpBPipeError	depth()/adepth() or chains()/achains() without a B-PIPE environment or the service entitlement

Attributes

Exception	Attributes
BlpRequestError and subclasses	service, operation, request_id (xbbg's label), bloomberg_request_id, bloomberg_request_ids, code
BlpSubscriptionDataLossError	The BlpRequestError attributes plus topic ("*" for session-wide loss) and detail
BlpTimeoutError	service, operation, request_id, bloomberg_request_id, bloomberg_request_ids when raised by the engine
BlpValidationError	element and suggestion (parsed from messages such as Unknown element 'x' (did you mean 'y'?)), valid_values, bloomberg_request_id, bloomberg_request_ids
Other classes	The message only

bloomberg_request_id holds the SDK request ID when exactly one request contributed and is None otherwise; bloomberg_request_ids always lists every known ID, possibly none. Give these IDs to Bloomberg support (see Entitlements and provenance). Attributes the engine did not know are None. Since 1.8.0, async calls build their exceptions lazily on the async bridge's completion thread; the classes and attributes are unchanged. A BlpTimeoutError you construct yourself has none of these attributes, so tests that build one should not rely on them.

import xbbg

try:
    frame = xbbg.bdh(["AAPL US Equity", "MSFT US Equity"], "PX_LAST", "2024-01-02", "2024-01-31")
except xbbg.BlpValidationError as exc:
    print("fix the call:", exc, exc.element, exc.suggestion)
except xbbg.BlpLimitError:
    print("Bloomberg capacity reached; retry later")
except xbbg.BlpRequestError as exc:
    print(exc.operation, exc.request_id, exc.bloomberg_request_ids)
except xbbg.BlpTimeoutError as exc:
    print("timed out:", exc.request_id, exc.bloomberg_request_ids)
except xbbg.BlpError as exc:
    print("other xbbg failure:", type(exc).__name__, exc)

Order the except clauses from specific to general: BlpLimitError before BlpRequestError, and BlpError last.

Built-in exceptions

Not every failure is a BlpError:

Exception	Typical causes
TypeError	An unknown keyword to configure() or Engine(); an unexpected keyword to a helper with a fixed signature, such as ext.cdx_ticker
ValueError	An ambiguous date such as "01/02/2024" (use ISO YYYY-MM-DD, YYYYMMDD, or date objects); configure(num_start_attempts=0); engine settings rejected when the engine is created (for example request_pool_size=0 or an unknown sdk_log_level); an unknown level for set_log_level or enable_sdk_logging; an unknown on_delayed or on_field_error policy on a subscription; invalid recipe arguments; set_sdk_path() with no SDK library in the directory
RuntimeError	A sync API called inside a running event loop outside notebooks; incomplete or inconsistent Bloomberg data in a recipe; bta when every security fails; iterating a rows=False subscription; a sync stream that waits more than 5 seconds for a subscription session
ImportError, ModuleNotFoundError	A missing or mismatched native extension, a missing Bloomberg runtime library, a missing optional dataframe backend, or the SDK test helpers without blpapi (see Troubleshooting)
NotImplementedError	Selecting a planned backend that has no conversion yet (cudf, modin, dask, ibis, pyspark, sqlframe); if its package is not installed, ImportError comes first
LookupError	xbbg.testing.mock_engine found no canned response (see Testing)
RustPanic	Since 1.8.0, a panic in native code while an async call converts its result is raised as the async bridge's RustPanic (an Exception subclass, not a BlpError) instead of leaving the awaitable pending; report it as a bug

Recipe failures

Since 1.5.0, xbbg.ext recipes raise the same typed BlpError subclasses as the request APIs when the engine fails, instead of RuntimeError. The rest of the contract:

• Invalid arguments raise ValueError: an unsupported earnings type, a non-generic futures or CDX ticker, a date before an index's first CDX series, an unknown volatility preset, an index_members field outside INDX_MWEIGHT, INDX_MEMBERS, and INDX_MEMBERS3.
• Incomplete or inconsistent Bloomberg data raises RuntimeError, for example missing CDX series metadata, an empty futures chain, or no rows for an index.
• Auction subscriptions raise BlpValidationError from their preflight; resolve_venues and auction_snapshot report failed inputs as rows instead of raising.
• When a composed recipe fails after some of its Bloomberg requests completed, the exception carries those requests' bloomberg_request_id(s), even when it is a ValueError or RuntimeError; read them with getattr(exc, "bloomberg_request_ids", []).

Partial failures

• Reference and historical data. A request raises BlpRequestError ("All securities failed: ...") only when every security fails. Otherwise the failing securities are left out of the rows, and the details travel as result metadata: security_errors ({ticker: {"category", "code", "subcategory", "message"}}), read from table.security_errors on native results, attrs["xbbg_security_errors"] on pandas, or the xbbg.security_errors schema metadata on PyArrow; and field_exceptions ({ticker: [{"field", "category", "code", "subcategory", "message"}]}), read from table.field_exceptions or attrs["xbbg_field_exceptions"], because since 1.8.0 its raw schema metadata is a compact envelope (see Entitlements and provenance). In bdp's default long format, include_security_errors=True also returns one __SECURITY_ERROR__ row per failed security, whose value reads code=... category=... subcategory=... message=...; with those rows, a bdp in which every security fails returns them instead of raising.
• Independent requests. Gather async requests with return_exceptions=True so one failure does not cancel the rest:

import asyncio

import xbbg


async def last_prices(tickers: list[str]) -> dict:
    results = await asyncio.gather(
        *(xbbg.abdp(ticker, "PX_LAST") for ticker in tickers),
        return_exceptions=True,
    )
    return dict(zip(tickers, results))


outcomes = asyncio.run(last_prices(["AAPL US Equity", "MSFT US Equity"]))
failed = {ticker: exc for ticker, exc in outcomes.items() if isinstance(exc, xbbg.BlpError)}

• Technical analysis. bta with several securities warns once per failed security and returns the rest; it raises RuntimeError only when all fail.
• Subscriptions. A rejected topic does not end its healthy siblings: inspect sub.failed_tickers, sub.failures, and sub.field_errors. Only continuity gaps and session termination end a stream (see Streaming).

Warnings

Warning	Base	Emitted when
BlpDelayedDataWarning	BlpSubscriptionWarning	A subscription topic is delayed (default on_delayed="warn"), or a request with on_delayed="warn" returns delayed data (once per security)
BlpFieldWarning	BlpSubscriptionWarning	Bloomberg rejects a requested subscription field, such as static-only PX_BID (on_field_error="warn")
BlpSubscriptionWarning	UserWarning	Base class for subscription diagnostics
RuntimeWarning		configure() is called after the engine started (the engine restarts with the new settings), or a source checkout's native extension was built from another commit
UserWarning		A keyword argument does not match the request schema and is passed to Bloomberg as is, a bta security fails, or no dataframe library is installed for the default Narwhals output
FutureWarning		Since 1.8.0, a result names its security column ticker, the default key column, which is deprecated because it collides with Bloomberg's TICKER field; pass key_column="security" to configure() or Engine() to switch

xbbg attributes request warnings to your calling line. Use the warnings module to silence, record, or escalate them:

import warnings

import xbbg

# Silence delayed-data warnings everywhere
warnings.filterwarnings("ignore", category=xbbg.BlpDelayedDataWarning)

# Turn every subscription diagnostic into an exception inside one block
with warnings.catch_warnings():
    warnings.simplefilter("error", xbbg.BlpSubscriptionWarning)
    prices = xbbg.bdp("VOD LN Equity", "PX_LAST", on_delayed="warn")

An escalated BlpDelayedDataWarning is raised as an exception from the call that would have warned. For requests, prefer on_delayed="raise", which raises BlpRequestError naming all delayed securities. In pytest, use -W error::xbbg.BlpDelayedDataWarning or a filterwarnings marker. Field type conversion misses are not Python warnings: they are logged by the native engine and counted in the type_misses result metadata (see Output formats).

Related pages

Exceptions API

Generated reference for xbbg.exceptions.

Troubleshooting

Import, connection, timeout, and empty-result diagnosis.

Entitlements

Delayed data, entitlement IDs, and support RequestIds.

Testing

Simulate failures in unit tests.