mostlyright.core.exceptions

Structured exception hierarchy for the mostlyright SDK and MCP server.

Every exception subclasses MostlyrightError and exposes a MostlyrightError.to_dict() method that returns a JSON-safe dict suitable for placement in the MCP error.data field of a JSON-RPC error response. Payload values are coerced via mostlyright.core._json_safe.to_json_safe() so the returned dict survives json.dumps without further customization.

Role names for SourceMismatchError are standardized as "observations", "forecasts", and "settlement". The column-prefix abbreviations obs_ / fcst_ / settle_ are NOT valid role names.

Module Attributes

Attribute	Description
DATA_AVAILABILITY_REASONS	Shared reason enum — MUST match TS lockstep.
DataAvailabilityReason	Type alias kept loose (str) rather than typing.Literal so callers passing a string variable don’t need to cast().

Exceptions

Exception	Description
ApiKeyRequiredError([message, error_code, …])	No MOSTLYRIGHT_API_KEY is configured.
CaptureNotAvailableError([message, …])	A webcast has no cold-fetchable HTTP media asset to capture.
ContractError([message, field, expected, …])	A frame or source spec violates its declared contract.
DataAvailabilityError([message, source, …])	Typed exception for “I tried to fetch and got nothing usable”.
DeprecatedModelWarning	Warning emitted when a deprecated NWP model is fetched.
EarningsError([message, error_code, source, …])	Base class for earnings-mention pipeline errors.
EarningsFactCorruptError([message, …])	An earnings fact row violates a column / identity contract.
ExperimentalFeatureWarning	Warning emitted when an EXPERIMENTAL, semver-exempt surface is first used.
GOESDataCorruptError([message, error_code, …])	NetCDF missing required attributes/variables, or shape unexpected.
GOESS3Error([message, error_code, source, …])	S3 (or GCS mirror) access failure after retries exhausted.
GRIBIntegrityError([message, variable, …])	A fetched GRIB2 byte-range failed structural / integrity validation.
HazardCacheCorruptError(path, reason, *[, …])	A persisted hazard cache partition exists but cannot be read.
HazardRetentionError([message, field, …])	The requested window is older than the live route’s retention limit.
HistoricalDepthError([message, …])	A requested NWP cycle is older than the archive’s depth.
IndicatorNotYetReleasedError(indicator, …)	A requested economic release is EXPECTED but has not been published yet.
IssuedAtMissingError([message, source, …])	A forecast row is missing the issued_at field.
KalshiCountRuleViolationError([message, …])	A Kalshi-counted occurrence carries an un-anchorable provenance.
LabelAlignmentError([message, namespace, …])	A user-supplied (BYO) label frame violated the aligner contract.
LeakageError([message, sample_violations, …])	Temporal leakage detected — at least one row has knowledge_time greater than the asserted as_of cutoff.
LiveStreamError([message, cause, source, …])	Base class for mostlyright.live.stream / live.latest failures.
LiveThrottledError([message, request_id, …])	The live source is rate-limiting us (HTTP 429) — the poll is refused.
ManifestUnavailableError([message, …])	A key is configured, but no manifest catalog could be obtained.
MeteosatCredentialsRequiredError([message, …])	A Meteosat SEVIRI fetch was attempted with no EUMETSAT Data-Store key.
MostlyrightError([message, error_code, …])	Base class for all mostlyright structured errors.
NWPError([message, error_code, source, …])	Base class for NWP forecast errors.
NWPModelNotAvailableError([message, …])	Model is declared in the public enum but not implemented in this version.
NWPModelRetiredError([message, model, …])	Caller asked for a model past its retirement date.
NoCWOPDataError(station, reason, *[, …])	No CWOP (APRS-IS) data available for the requested station/area.
NoDataError([message, cause, source, …])	No usable data was produced for the requested entity/window.
NoHazardDataError(identifier, reason, *[, …])	A named hazard identity produced no rows.
NoLiveDataError([message, request_id, …])	mostlyright.live.latest() returned no observations for the station.
NoLiveForNWPError([message, mirrors_tried, …])	All wired mirrors failed to serve a live cycle for (model, cycle).
OpenMeteoSeamlessLeakageError([message, …])	The Open-Meteo Historical Forecast (seamless) endpoint was used without allow_leakage=True opt-in.
PayloadTooLargeError([message, …])	The MCP server rejected an inline payload whose declared size exceeded the cap.
ProductNotRegisteredError([message, …])	(product, variable) pair not in the PRODUCTS registry.
ReleaseScheduleUnavailableError([message, …])	A release-schedule source answered, but the body carried no usable schedule.
SatelliteError([message, error_code, …])	Base class for GOES ABI L2 satellite ingest errors.
SatelliteFilenameParseError([message, …])	An object name does not carry the scan timestamps the product expects.
SatelliteRetrievalTimeoutError([message, …])	A bounded satellite retrieval ran past its wall-clock budget.
SchemaValidationError([message, violations, …])	A DataFrame failed schema validation.
SourceMismatchError([message, role, …])	The data’s source does not match the schema’s registered source, and the caller did not opt out via source_drift_reason.
SourceUnavailableError([message, source, …])	A source (HTTP endpoint, vendored parser, etc.) returned an error or was otherwise unreachable.
StationOutOfGridError([message, error_code, …])	Station projection lands outside the product grid.
StormNotFoundError([message, query, …])	A HAFS storm query (id or name) doesn’t match any active storm.
TemporalDriftError([message, …])	Raised by the reproducibility audit when one or more rows have retrieved_at outside the asserted range AND fall within the volatile window of now.
UnitsContractError([message, error_code, …])	NetCDF variable units attribute does not match the registry.
UnsupportedResolutionError([message, …])	An interval= value is outside the venue’s supported resolution set.
VenueCapabilityError([message, venue, …])	A verb exists in the shared venue grammar but this venue has no such concept.

exception mostlyright.core.exceptions.ApiKeyRequiredError(message=”, , error_code=None, source=None, request_id=None)

Bases: MostlyrightError

No MOSTLYRIGHT_API_KEY is configured.

Raised at CALL time by the manifest resolvers (mostlyright._internal._manifest_resolve) — source addresses resolve through the hosted manifest, and the manifest requires an active subscription’s API key (founder decision, August 2026; replaces the former vendored-catalog fallback and its KeylessDecayWarning, both deleted). Importing any vertical never raises this; only resolving does.

The fix the message names: set MOSTLYRIGHT_API_KEY to a key from https://app.mostlyright.md.

• Parameters:
  • message (str)
  • error_code (str)
  • source (str | None)
  • request_id (str | None)
• Return type: None

exception mostlyright.core.exceptions.CaptureNotAvailableError(message=”, , error_code=None, source=None, request_id=None)

Bases: EarningsError

A webcast has no cold-fetchable HTTP media asset to capture.

Raised by a capture adapter when the provider template is not an HTTP-media webcast — for example Q4’s analyst template, which is a telephone dial-in (meeting ID plus passcode, with no media or CDN host ever requested). The caller should route to dial-in capture or skip the webcast, rather than emit empty audio. This is a normal control signal, not a corruption, and subclasses EarningsError so callers can filter it cleanly.

• Parameters:
  • message (str)
  • error_code (str)
  • source (str | None)
  • request_id (str | None)
• Return type: None

default_error_code: str

Subclass override — the stable string enum surfaced via error_code.

exception mostlyright.core.exceptions.ContractError(message=”, , field=None, expected=None, actual=None, location=None, doc_url=None, source=None, request_id=None, error_code=None)

Bases: MostlyrightError

A frame or source spec violates its declared contract.

Modelled on SchemaValidationError but for the two-axis align(spine, *sources) world: raised when a SourceContract is malformed (e.g. a prefix that does not end with "_") or when a source/spine frame does not conform at compose time. field names the offending contract field so the copy (built via mostlyright._errmsg.contract_message()) points the user at the exact thing to change.

• Parameters:
  • message (str)
  • field (str | None)
  • expected (str | None)
  • actual (str | None)
  • location (str | None)
  • doc_url (str | None)
  • source (str | None)
  • request_id (str | None)
  • error_code (str)
• Return type: None

actual: str | None

default_error_code: str

Subclass override — the stable string enum surfaced via error_code.

doc_url: str | None

error_code: str

expected: str | None

field: str | None

location: str | None

message: str

request_id: str | None

source: str | None

mostlyright.core.exceptions.DATA_AVAILABILITY_REASONS : tuple[str, …]

Shared reason enum — MUST match TS lockstep. The TS exception in packages-ts/core/src/exceptions/index.ts defines an identical array under DATA_AVAILABILITY_REASONS. Drift here invalidates every cross-SDK except DataAvailabilityError as e: if e.reason == ... branch a consumer writes.

exception mostlyright.core.exceptions.DataAvailabilityError(message=”, , reason, hint, source=None, request_id=None, error_code=None)

Bases: MostlyrightError

Typed exception for “I tried to fetch and got nothing usable”.

Raised where a fetch completed but produced nothing usable: a forecast model is unavailable, an AWC request falls outside the 168h window, an IEM cache misses, a fetcher returns 404/5xx, or the source rate-limits. Consumers branch on reason instead of string-matching message:

try: : df = tw.research(…)

except DataAvailabilityError as e: : if e.reason == “out_of_window”: : … # widen the window
elif e.reason == “rate_limited”: : … # back off
else: : raise

The reason enum is shared lockstep with the TypeScript SDK — see DATA_AVAILABILITY_REASONS and the matching const array in packages-ts/core/src/exceptions/index.ts. Drift between SDKs is the load-bearing risk.

SourceUnavailableError remains in place for back-compat; new code prefers DataAvailabilityError.

• Parameters:
  • message (str)
  • reason (str)
  • hint (str)
  • source (str | None)
  • request_id (str | None)
  • error_code (str)
• Return type: None

default_error_code: str

Subclass override — the stable string enum surfaced via error_code.

mostlyright.core.exceptions.DataAvailabilityReason

Type alias kept loose (str) rather than typing.Literal so callers passing a string variable don’t need to cast(). Construction-time validation in DataAvailabilityError.__init__ enforces the enum.

exception mostlyright.core.exceptions.DeprecatedModelWarning

Bases: DeprecationWarning

Warning emitted when a deprecated NWP model is fetched.

Used for NAM / HREF / HiResW which retire 31 Aug 2026 per NWS scn26-47 (Herbie issue #540). Subclass of DeprecationWarning so callers can promote it to an error via warnings.filterwarnings("error", category=DeprecatedModelWarning).

exception mostlyright.core.exceptions.EarningsError(message=”, , error_code=None, source=None, request_id=None)

Bases: MostlyrightError

Base class for earnings-mention pipeline errors.

Covers the canonical earnings schemas (schema.finance.transcript.v1 / schema.finance.fact.v1) and their contract hooks. Each subclass maps a single failure mode of the fact-ledger build path, the same way the SatelliteError and NWPError families are organized.

• Parameters:
  • message (str)
  • error_code (str)
  • source (str | None)
  • request_id (str | None)
• Return type: None

default_error_code: str

Subclass override — the stable string enum surfaced via error_code.

exception mostlyright.core.exceptions.EarningsFactCorruptError(message=”, , error_code=None, source=None, request_id=None)

Bases: EarningsError

An earnings fact row violates a column / identity contract.

Raised by the schema hooks (e.g. validate_ticker()) when a row’s ticker or other contract field is malformed — mirrors GOESDataCorruptError / validate_satellite_station.

• Parameters:
  • message (str)
  • error_code (str)
  • source (str | None)
  • request_id (str | None)
• Return type: None

default_error_code: str

Subclass override — the stable string enum surfaced via error_code.

exception mostlyright.core.exceptions.ExperimentalFeatureWarning

Bases: UserWarning

Warning emitted when an EXPERIMENTAL, semver-exempt surface is first used.

The contributor registry (mostlyright.experimental.contributor()) is public-experimental and semver-exempt until it graduates — its contribute() protocol, registry surface, and compose semantics may change in any minor release. This warning fires ONCE per session, on the FIRST third-party registration (the four built-in contributors — forecasts / trades / satellite / cwop — are exempt so the default dataset() path stays warning-free).

Subclass of UserWarning (NOT DeprecationWarning) because the feature is not being removed — it is provisional. Callers who want to treat experimental usage as an error can promote it via warnings.filterwarnings("error", category=ExperimentalFeatureWarning).

exception mostlyright.core.exceptions.GOESDataCorruptError(message=”, , error_code=None, source=None, request_id=None)

Bases: SatelliteError

NetCDF missing required attributes/variables, or shape unexpected.

• Parameters:
  • message (str)
  • error_code (str)
  • source (str | None)
  • request_id (str | None)
• Return type: None

default_error_code: str

Subclass override — the stable string enum surfaced via error_code.

exception mostlyright.core.exceptions.GOESS3Error(message=”, , error_code=None, source=None, request_id=None)

Bases: SatelliteError

S3 (or GCS mirror) access failure after retries exhausted.

• Parameters:
  • message (str)
  • error_code (str)
  • source (str | None)
  • request_id (str | None)
• Return type: None

default_error_code: str

Subclass override — the stable string enum surfaced via error_code.

exception mostlyright.core.exceptions.GRIBIntegrityError(message=”, , model, variable=None, byte_offset=None, byte_end=None, underlying=”, request_id=None, error_code=None)

Bases: NWPError

A fetched GRIB2 byte-range failed structural / integrity validation.

Raised when the GRIB2 record retrieved via byte-range does not match its .idx claim, decodes with missing variables, or cfgrib surfaces an “unexpected end of message” / “messages out of order” error. Carries the variable that triggered the error plus the (byte_offset, byte_end) of the offending record so the caller can replay or skip.

• Parameters:
  • message (str)
  • model (str)
  • variable (str | None)
  • byte_offset (int | None)
  • byte_end (int | None)
  • underlying (str)
  • request_id (str | None)
  • error_code (str)
• Return type: None

default_error_code: str

Subclass override — the stable string enum surfaced via error_code.

exception mostlyright.core.exceptions.HazardCacheCorruptError(path, reason, , request_id=None, error_code=None)

Bases: MostlyrightError

A persisted hazard cache partition exists but cannot be read.

Descends MostlyrightError DIRECTLY. A torn parquet partition is neither a ContractError (the caller did nothing wrong) nor a NoDataError (the rows exist — they are unreadable). Giving it either parent would let a caller’s except NoDataError swallow a corrupt on-disk vintage as “no data”, which is exactly the silent-corruption path the hazards vintage store exists to prevent.

The message carries the absolute path and the literal recovery command so the user does not have to guess which file to move aside.

• Parameters:
  • path (Path)
  • reason (str)
  • request_id (str | None)
  • error_code (str)
• Return type: None

default_error_code: str

Subclass override — the stable string enum surfaced via error_code.

exception mostlyright.core.exceptions.HazardRetentionError(message=”, , field=None, expected=None, actual=None, location=None, doc_url=None, source=None, request_id=None, error_code=None)

Bases: ContractError

The requested window is older than the live route’s retention limit.

api.weather.gov/alerts and api.weather.gov/products both retain exactly 7 days: a start seven days back returns rows, and eight days back returns zero features. Asking the live route for an older window is a caller contract violation caught BEFORE any I/O — it is not a data-availability failure and it never degrades to an empty frame.

The fix the message carries is a source= pin, not a second verb name: source="iem" routes the same call at the Iowa State VTEC/AFOS archive, which has no 7-day cliff. Keeping the fix on a parameter rather than on a separate archive verb is what lets this teaching error survive a verb rename.

Takes the ContractError signature unchanged (field/expected/actual) so the structured teaching payload is the same one every other contract violation in the SDK emits.

• Parameters:
  • message (str)
  • field (str | None)
  • expected (str | None)
  • actual (str | None)
  • location (str | None)
  • doc_url (str | None)
  • source (str | None)
  • request_id (str | None)
  • error_code (str)
• Return type: None

default_error_code: str

Subclass override — the stable string enum surfaced via error_code.

exception mostlyright.core.exceptions.HistoricalDepthError(message=”, , model, requested_cycle=None, archive_depth=None, request_id=None, error_code=None)

Bases: NWPError

A requested NWP cycle is older than the archive’s depth.

Each NWP model has an AWS BDP archive depth (HRRR from 30 Jul 2014, GFS from 1 Jan 2021, GEFS from 1 Jan 2017, NBM from 2020, ECMWF IFS from 1 Jan 2022, AIFS from 25 Feb 2024). MSC family always raises (24h Datamart retention) — pass archive_depth=None for the live-only case.

• Parameters:
  • message (str)
  • model (str)
  • requested_cycle (datetime | None)
  • archive_depth (datetime | None)
  • request_id (str | None)
  • error_code (str)
• Return type: None

model

Model id (e.g. "hrrr", "hrdps").

requested_cycle

UTC datetime the caller asked for.

archive_depth

Earliest cycle the archive holds, or None for live-only models (MSC 24h retention, NOMADS-only legacy).

default_error_code: str

Subclass override — the stable string enum surfaced via error_code.

exception mostlyright.core.exceptions.HttpError(message, status_code=None)

Bases: MostlyrightError

Base exception for mostlyright HTTP transport errors.

Subclass of MostlyrightError so catching MostlyrightError also catches transport errors. status_code is the only transport-specific attribute; structured error_code / source / request_id flow through MostlyrightError.__init__.

• Parameters:
  • message (str)
  • status_code (int | None)

exception mostlyright.core.exceptions.IndicatorNotYetReleasedError(indicator, period, , expected_release=None, remedy=None, source=None, request_id=None, error_code=None)

Bases: MostlyrightError

A requested economic release is EXPECTED but has not been published yet.

For economic releases, “not yet released” is a normal, branchable state distinct from “unavailable”: the release calendar says a print is due, but no vintage_time exists for that period yet. The economy verbs (economy.series / economy.releases / economy.training_table) raise this instead of returning [] / None, so a caller can tell “the data is genuinely gone” (a DataAvailabilityError) apart from “come back after the 8:30 ET release” (this error) and, when the time is known, retry at expected_release.

Defined in core rather than packages/economy for the same reason as EarningsError and NoCWOPDataError: the exception taxonomy is centralized so MCP JSON-RPC serialization and Python/TypeScript lockstep apply uniformly. mostlyright.economy re-exports it.

• Parameters:
  • indicator (str)
  • period (str)
  • expected_release (datetime | None)
  • remedy (str | None)
  • source (str | None)
  • request_id (str | None)
  • error_code (str)
• Return type: None

indicator

The indicator id ("cpi", "nfp", "gdp", …).

period

The observation period requested ("2026-06", "2026Q2", an FOMC meeting date, …).

expected_release

The scheduled release wall-clock when known, else None (the payload never fabricates a timestamp).

remedy

An optional actionable hint for how to unlock the value (for example, that the settlement-grade first print needs FRED_API_KEY). It has its own field — included in the message body and in _payload() — so period stays a real observation period and never carries a hint.

default_error_code: str

Subclass override — the stable string enum surfaced via error_code.

exception mostlyright.core.exceptions.IssuedAtMissingError(message=”, , source=None, violating_count=0, sample_violations=None, request_id=None, error_code=None)

Bases: SchemaValidationError

A forecast row is missing the issued_at field.

Raised when a forecast row would land in the DataFrame with issued_at IS NULL. For Open-Meteo Previous Runs API this should be impossible by construction (the fetcher derives issued_at per row via the conservative lower-bound formula). For Live mode, this is raised when cycle-math fallback cannot derive a non-null cycle.

This prevents seamless forecast rows without a reliable issue time from entering point-in-time training data.

• Parameters:
  • message (str)
  • source (str | None)
  • violating_count (int)
  • sample_violations (list [dict [str , Any ] ])
  • request_id (str | None)
  • error_code (str)
• Return type: None

default_error_code: str

Subclass override — the stable string enum surfaced via error_code.

exception mostlyright.core.exceptions.KalshiCountRuleViolationError(message=”, , role_source=None, speaker_role=None, source=None, request_id=None, error_code=None)

Bases: EarningsError

A Kalshi-counted occurrence carries an un-anchorable provenance.

Raised by validate_kalshi_counted_occurrence in strict mode when an occurrence asserted as Kalshi-counted has role_source not in {transcript_structural, transcript_self_id, roster_match} OR speaker_role not in {company_executive, operator_ir} (fail-closed). Carries the offending role_source / speaker_role so callers and audit logs can see exactly why the occurrence was excluded — mirrors how StationOutOfGridError surfaces station/satellite via _payload.

• Parameters:
  • message (str)
  • role_source (str | None)
  • speaker_role (str | None)
  • source (str | None)
  • request_id (str | None)
  • error_code (str)
• Return type: None

default_error_code: str

Subclass override — the stable string enum surfaced via error_code.

exception mostlyright.core.exceptions.LabelAlignmentError(message=”, , reason, namespace=None, column=None, source=None, request_id=None, error_code=None)

Bases: MostlyrightError

A user-supplied (BYO) label frame violated the aligner contract.

Raised by mostlyright._labels.align_byo_labels() when a bring-your-own label DataFrame cannot be aligned to the station settlement calendar without ambiguity or a silent data hazard. Every rejection raises: the aligner never silently drops rows, guesses a date column, or ignores a publication-lag request.

reason is a stable enum so a caller can branch without parsing the message text:

• "missing_date" — no date column and no coercible datetime index.
• "missing_station_panel" — panel call (multi-station) but the frame has no station column.
• "station_disagree" — a single-station call whose frame carries a station column that disagrees with the call’s station.
• "collision" — a bring-your-own label column collides with a reserved namespace: a label recipe column, a registered feature prefix, or a core observed_* / daily_summary_* name. namespace names which one was hit.
• "publication_lag_no_published_at" — labels_as_known= "publication_lag" requested but the frame carries no published_at column (never a silent no-op).

• Parameters:
  • message (str)
  • reason (str)
  • namespace (str | None)
  • column (str | None)
  • source (str | None)
  • request_id (str | None)
  • error_code (str)
• Return type: None

VALID_REASONS

Stable rejection-reason vocabulary for the bring-your-own label aligner. Shared lockstep with the TS LABEL_ALIGNMENT_REASONS.

default_error_code: str

Subclass override — the stable string enum surfaced via error_code.

exception mostlyright.core.exceptions.LeakageError(message=”, , as_of, violating_count, sample_violations=None, column=None, boundary=None, decision_time=None, doc_url=None, source=None, request_id=None, error_code=None)

Bases: MostlyrightError

Temporal leakage detected — at least one row has knowledge_time greater than the asserted as_of cutoff. Carries the count and a small sample of violating rows for actionable surfacing.

• Parameters:
  • message (str)
  • as_of (str)
  • violating_count (int)
  • sample_violations (list [dict [str , Any ] ])
  • column (str | None)
  • boundary (str | None)
  • decision_time (str | None)
  • doc_url (str | None)
  • source (str | None)
  • request_id (str | None)
  • error_code (str)
• Return type: None

as_of: str

boundary: str | None

column: str | None

decision_time: str | None

default_error_code: str

Subclass override — the stable string enum surfaced via error_code.

doc_url: str | None

error_code: str

message: str

request_id: str | None

sample_violations: list[dict[str, Any]]

source: str | None

violating_count: int

exception mostlyright.core.exceptions.LiveStreamError(message=”, , cause=None, source=None, request_id=None, error_code=None)

Bases: NoDataError

Base class for mostlyright.live.stream / live.latest failures.

Live-streaming errors are deliberately a separate sub-tree from SourceUnavailableError because the recovery path differs — for a live stream, the caller is in a polling loop and “no data yet” is the COMMON case, not an exception. NoLiveDataError is only raised by the one-shot mostlyright.live.latest() surface; mostlyright.live.stream() swallows empty-tick errors and waits for the next polite-floor cycle.

Descends NoDataError, so NoLiveDataError and NoCWOPDataError sit in the NoDataError sub-tree while keeping their LiveStreamError ancestry. default_error_code is LIVE_STREAM_ERROR.

• Parameters:
  • message (str)
  • cause (str | None)
  • source (str | None)
  • request_id (str | None)
  • error_code (str)
• Return type: None

default_error_code: str

Subclass override — the stable string enum surfaced via error_code.

exception mostlyright.core.exceptions.LiveThrottledError(message=”, , station, source, retry_after_seconds, request_id=None, error_code=None)

Bases: NoLiveDataError

The live source is rate-limiting us (HTTP 429) — the poll is refused.

Raised by the live.latest/live.stream IEM leg in two situations: an upstream 429 just occurred (and a cooldown was recorded), or a previously-recorded cooldown is still active — in which case the poll fails FAST without touching the network, so a fleet poller backs off instead of re-tripping IEM’s per-IP throttle on every cycle.

Subclass of NoLiveDataError so existing skip/except paths keep working (stream() skips the tick); callers that want to branch catch this class and honor retry_after_seconds.

• Parameters:
  • message (str)
  • station (str)
  • source (str | None)
  • retry_after_seconds (float)
  • request_id (str | None)
  • error_code (str)
• Return type: None

default_error_code: str

Subclass override — the stable string enum surfaced via error_code.

exception mostlyright.core.exceptions.ManifestUnavailableError(message=”, , error_code=None, source=None, request_id=None)

Bases: MostlyrightError

A key is configured, but no manifest catalog could be obtained.

Three distinct paths raise this, and the message says which:

• the endpoint REJECTED the key (HTTP 401/402/403) — revoked key or lapsed subscription. Deliberately raised without consulting the local cache, so a cancelled subscription stops resolving at its next fetch window instead of coasting on a warm cache;

• a transient failure (network error, 5xx, malformed body) with no local cache to fall back on;

• the internal MOSTLYRIGHT_MANIFEST_PATH seam points at an unreadable or malformed file.

• Parameters:

  • message (str)
  • error_code (str)
  • source (str | None)
  • request_id (str | None)

• Return type: None

exception mostlyright.core.exceptions.MeteosatCredentialsRequiredError(message=”, , source=None, http_status=None, retryable=False, retry_after_s=None, underlying=”, url=None, request_id=None, error_code=None)

Bases: SatelliteError, SourceUnavailableError

A Meteosat SEVIRI fetch was attempted with no EUMETSAT Data-Store key.

Meteosat is the ONLY keyed source in the native ring: GOES / Himawari / VIIRS pull anonymous public NOAA buckets, but Meteosat SEVIRI pulls the EUMETSAT Data Store, which is OAuth2-gated.

This is raised rather than falling back to another instrument ON PURPOSE. Europe, Africa and the Indian Ocean auto-route to Meteosat by GEOGRAPHY, and that routing must not change depending on whether a credential happens to be present in the environment: a key-dependent fallback would silently train a model on VIIRS rows and infer on SEVIRI rows for the same station, which is exactly the train/infer source mismatch the SDK’s source-identity invariants exist to prevent.

The message names all three exits — register for a free EUMETSAT Data Store account, use the opt-in hosted delivery path, or ask for an explicit satellite="viirs-*" — and NEVER echoes a credential value.

It is BOTH a SatelliteError (so it belongs to the satellite family the backfill orchestrator handles per file) AND a SourceUnavailableError (so every existing except SourceUnavailableError: raise guard on the keyed transport keeps letting it through instead of laundering it into a generic download failure). Narrowing it to one base would silently change one of those two behaviours.

• Parameters:
  • message (str)
  • source (str | None)
  • http_status (int | None)
  • retryable (bool)
  • retry_after_s (float | None)
  • underlying (str)
  • url (str | None)
  • request_id (str | None)
  • error_code (str)
• Return type: None

default_error_code: str

Subclass override — the stable string enum surfaced via error_code.

exception mostlyright.core.exceptions.MostlyrightError(message=”, , error_code=None, source=None, request_id=None)

Bases: Exception

Base class for all mostlyright structured errors.

error_code is a stable enum (e.g. "SOURCE_UNAVAILABLE") used by callers / agents to branch on without parsing message text. source is the source ID involved ("iem.archive" etc.) when applicable, and request_id correlates an MCP JSON-RPC request when applicable.

• Parameters:
  • message (str)
  • error_code (str)
  • source (str | None)
  • request_id (str | None)
• Return type: None

default_error_code: str

Subclass override — the stable string enum surfaced via error_code.

error_code: str

message: str

request_id: str | None

source: str | None

to_dict()

Return a JSON-safe dict suitable for MCP error.data.

• Return type: dict[str, Any]

exception mostlyright.core.exceptions.NWPError(message=”, , error_code=None, source=None, request_id=None)

Bases: MostlyrightError

Base class for NWP forecast errors.

Subclasses cover the three failure modes a quant fetching live NWP data hits in practice: an unsupported model (ECMWF Tier-2 reserved for v0.2), no live cycle reachable from any wired mirror, or decoded GRIB2 bytes that failed integrity / structural validation.

• Parameters:
  • message (str)
  • error_code (str)
  • source (str | None)
  • request_id (str | None)
• Return type: None

default_error_code: str

Subclass override — the stable string enum surfaced via error_code.

exception mostlyright.core.exceptions.NWPModelNotAvailableError(message=”, , model, available_in=‘v0.2’, request_id=None, error_code=None)

Bases: NWPError

Model is declared in the public enum but not implemented in this version.

Raised for models that are part of the shared schema but do not have a working fetch path in this SDK. model carries the requested model id; available_in is retained for serialized-error compatibility.

• Parameters:
  • message (str)
  • model (str)
  • available_in (str)
  • request_id (str | None)
  • error_code (str)
• Return type: None

default_error_code: str

Subclass override — the stable string enum surfaced via error_code.

exception mostlyright.core.exceptions.NWPModelRetiredError(message=”, , model=”, retired_on=None, replacement_suggestions=None, request_id=None, error_code=None)

Bases: NWPError

Caller asked for a model past its retirement date.

NAM / HREF / HiResW retire 31 Aug 2026 per NWS scn26-47 (Herbie issue #540). The retirement date is loaded from mostlyright.weather._fetchers._url_transitions.LEGACY_MODELS_RETIRE. Carries replacement_suggestions so callers can wire a graceful fallback (HRRR / RAP / RRFS).

• Parameters:
  • message (str)
  • model (str)
  • retired_on (datetime | None)
  • replacement_suggestions (list [str ])
  • request_id (str | None)
  • error_code (str)
• Return type: None

default_error_code: str

Subclass override — the stable string enum surfaced via error_code.

exception mostlyright.core.exceptions.NoCWOPDataError(station, reason, , request_id=None, error_code=None)

Bases: NoLiveDataError

No CWOP (APRS-IS) data available for the requested station/area.

Raised by the standalone mostlyright.weather.cwop surface (scan/nearby/stream/snapshot/latest) instead of returning []/None, so callers get an actionable signal — CWOP is a live-only TCP stream and “nothing arrived” is the common failure mode (the station never reported, the area is empty, or the listen window was too short). Carries the resolved station/area identifier, the fixed source="cwop.live" tag, and a human-readable reason.

• Parameters:
  • station (str)
  • reason (str)
  • request_id (str | None)
  • error_code (str)
• Return type: None

default_error_code: str

Subclass override — the stable string enum surfaced via error_code.

exception mostlyright.core.exceptions.NoDataError(message=”, , cause=None, source=None, request_id=None, error_code=None)

Bases: MostlyrightError

No usable data was produced for the requested entity/window.

The base class for “I asked and got nothing” across domains; NoLiveDataError and NoCWOPDataError live under it, so align and contract code can catch one stable name. The optional cause names which fact failed (empty window, unknown entity, source gap), so a valid zero-row result is distinguishable from a broken feed.

• Parameters:
  • message (str)
  • cause (str | None)
  • source (str | None)
  • request_id (str | None)
  • error_code (str)
• Return type: None

cause: str | None

default_error_code: str

Subclass override — the stable string enum surfaced via error_code.

error_code: str

message: str

request_id: str | None

source: str | None

exception mostlyright.core.exceptions.NoHazardDataError(identifier, reason, , source=‘hazards.cache’, request_id=None, error_code=None)

Bases: NoDataError

A named hazard identity produced no rows.

Raised by the mostlyright.weather.hazards identity verbs — the ones that are handed a specific storm id, product id, or zone — instead of returning []/None. Carries the identifier that was asked for, the human-readable reason, and the source tag of the route that answered.

Parented on NoDataError, NOT on NoLiveDataError: a valid finite query that returns zero rows is a zero-row answer, not a live-capture failure. The shape (positional identifier + reason, keyword-only source, the _payload override) mirrors NoCWOPDataError; only the parentage differs, deliberately.

Enumeration verbs do NOT raise this. hazards.tropical_cyclones() in a quiet season returns a schema-valid EMPTY frame, because CurrentStorms.json serving {"activeStorms": []} is a correct answer about the world. A missing NAMED identity is not.

• Parameters:
  • identifier (str)
  • reason (str)
  • source (str | None)
  • request_id (str | None)
  • error_code (str)
• Return type: None

default_error_code: str

Subclass override — the stable string enum surfaced via error_code.

exception mostlyright.core.exceptions.NoLiveDataError(message=”, , station, source, request_id=None, error_code=None)

Bases: LiveStreamError

mostlyright.live.latest() returned no observations for the station.

Carries the resolved ICAO station and the canonical source identity tag ("awc.live" / "iem.live") so caller logs can branch by source without re-parsing the message.

• Parameters:
  • message (str)
  • station (str)
  • source (str | None)
  • request_id (str | None)
  • error_code (str)
• Return type: None

default_error_code: str

Subclass override — the stable string enum surfaced via error_code.

exception mostlyright.core.exceptions.NoLiveForNWPError(message=”, , model, mirrors_tried=None, last_status=None, request_id=None, error_code=None)

Bases: NWPError

All wired mirrors failed to serve a live cycle for (model, cycle).

Carries the mirror chain that was tried and the per-mirror failure summary so callers can audit why every fallback failed. Distinct from SourceUnavailableError because the recovery action is different — for NWP, the typical fix is to wait for the next cycle rather than retry the same one.

• Parameters:
  • message (str)
  • model (str)
  • mirrors_tried (list [str ])
  • last_status (int | None)
  • request_id (str | None)
  • error_code (str)
• Return type: None

default_error_code: str

Subclass override — the stable string enum surfaced via error_code.

exception mostlyright.core.exceptions.OpenMeteoSeamlessLeakageError(message=”, , model=”, endpoint_url=”, as_of=None, violating_count=0, sample_violations=None, source=None, request_id=None, error_code=None)

Bases: LeakageError

The Open-Meteo Historical Forecast (seamless) endpoint was used without allow_leakage=True opt-in.

The seamless endpoint silently stitches forecasts from multiple model cycles into a continuous timeseries; the cycle that produced each value is unrecoverable from the response. LeakageDetector rejects rows tagged source="open_meteo.seamless" whenever as_of is asserted.

• Parameters:
  • message (str)
  • model (str)
  • endpoint_url (str)
  • as_of (str)
  • violating_count (int)
  • sample_violations (list [dict [str , Any ] ])
  • source (str | None)
  • request_id (str | None)
  • error_code (str)
• Return type: None

default_error_code: str

Subclass override — the stable string enum surfaced via error_code.

exception mostlyright.core.exceptions.PayloadTooLargeError(message=”, , declared_size, limit, accepted_modes=None, source=None, request_id=None, error_code=None)

Bases: MostlyrightError

The MCP server rejected an inline payload whose declared size exceeded the cap. accepted_modes advertises alternatives such as file-path mode.

• Parameters:
  • message (str)
  • declared_size (int)
  • limit (int)
  • accepted_modes (list [str ])
  • source (str | None)
  • request_id (str | None)
  • error_code (str)
• Return type: None

accepted_modes: list[str]

declared_size: int

default_error_code: str

Subclass override — the stable string enum surfaced via error_code.

error_code: str

limit: int

message: str

request_id: str | None

source: str | None

exception mostlyright.core.exceptions.ProductNotRegisteredError(message=”, , error_code=None, source=None, request_id=None)

Bases: SatelliteError

(product, variable) pair not in the PRODUCTS registry.

• Parameters:
  • message (str)
  • error_code (str)
  • source (str | None)
  • request_id (str | None)
• Return type: None

default_error_code: str

Subclass override — the stable string enum surfaced via error_code.

exception mostlyright.core.exceptions.ReleaseScheduleUnavailableError(message=”, , source=None, http_status=None, retryable=False, retry_after_s=None, underlying=”, url=None, request_id=None, error_code=None)

Bases: SourceUnavailableError

A release-schedule source answered, but the body carried no usable schedule.

Raised when a schedule leg returns a body that parses to zero usable events, or an event whose release-type token is outside the mapped vocabulary. An empty schedule is an explicit error, never a silently-empty return: a caller that receives an empty calendar reads it as “every future release is cancelled”, which is the wrong answer to a bot-wall page, an HTML landing page served at HTTP 200, or an unfolded line the parser dropped.

Subclasses SourceUnavailableError so an existing except SourceUnavailableError block still catches it, and inherits that constructor unchanged — source= / url= / http_status= carry the same meaning. The distinct error_code (RELEASE_SCHEDULE_UNAVAILABLE, shared byte-for-byte with the TypeScript mirror) is what lets a caller that cares tell “the endpoint answered with nothing usable” apart from “the endpoint was unreachable”.

• Parameters:
  • message (str)
  • source (str | None)
  • http_status (int | None)
  • retryable (bool)
  • retry_after_s (float | None)
  • underlying (str)
  • url (str | None)
  • request_id (str | None)
  • error_code (str)
• Return type: None

default_error_code: str

Subclass override — the stable string enum surfaced via error_code.

exception mostlyright.core.exceptions.SatelliteError(message=”, , error_code=None, source=None, request_id=None)

Bases: MostlyrightError

Base class for GOES ABI L2 satellite ingest errors.

The extractor (_goes_extract.py) and S3 transport (_goes_s3.py) raise these structured errors. Each subclass maps a single failure mode of the single-pixel extraction path.

• Parameters:
  • message (str)
  • error_code (str)
  • source (str | None)
  • request_id (str | None)
• Return type: None

default_error_code: str

Subclass override — the stable string enum surfaced via error_code.

exception mostlyright.core.exceptions.SatelliteFilenameParseError(message=”, , error_code=None, source=None, request_id=None)

Bases: SatelliteError

An object name does not carry the scan timestamps the product expects.

Raised by the extractors’ parse_scan_times when a bucket listing returns a name from a different era or a different naming convention. It is a SatelliteError on purpose: the backfill orchestrator catches that base class per file, so an unreadable name SKIPS one object instead of killing the whole batch task with an uncaught ValueError.

• Parameters:
  • message (str)
  • error_code (str)
  • source (str | None)
  • request_id (str | None)
• Return type: None

default_error_code: str

Subclass override — the stable string enum surfaced via error_code.

exception mostlyright.core.exceptions.SatelliteRetrievalTimeoutError(message=”, , error_code=None, source=None, request_id=None)

Bases: GOESS3Error

A bounded satellite retrieval ran past its wall-clock budget.

Distinct from the plain GOESS3Error it subclasses because the two call for different handling. A generic transport failure means the fetch did not work. A timeout means the server accepted the connection and then stopped delivering, which is a transient worth one bounded retry and is not a reason to keep waiting: without a deadline, a single stalled deep-archive product can hold a backfill segment open for hours while nothing is written. Raising skips one product; waiting loses the segment.

Subclassing GOESS3Error keeps every existing except GOESS3Error / except SatelliteError handler catching it unchanged.

• Parameters:
  • message (str)
  • error_code (str)
  • source (str | None)
  • request_id (str | None)
• Return type: None

default_error_code: str

Subclass override — the stable string enum surfaced via error_code.

exception mostlyright.core.exceptions.SchemaValidationError(message=”, , schema_id, violations=None, quarantine_count=0, sample_violations=None, source=None, request_id=None, error_code=None)

Bases: MostlyrightError

A DataFrame failed schema validation. Carries the full violation list (capped at 10,000 entries — the SDK writes the surplus to a file and returns its path) and a small inline sample for MCP wire serialization (≤10 entries).

• Parameters:
  • message (str)
  • schema_id (str)
  • violations (list [dict [str , Any ] ])
  • quarantine_count (int)
  • sample_violations (list [dict [str , Any ] ])
  • source (str | None)
  • request_id (str | None)
  • error_code (str)
• Return type: None

default_error_code: str

Subclass override — the stable string enum surfaced via error_code.

error_code: str

message: str

quarantine_count: int

request_id: str | None

sample_violations: list[dict[str, Any]]

schema_id: str

source: str | None

violations: list[dict[str, Any]]

exception mostlyright.core.exceptions.SourceMismatchError(message=”, , schema_source, data_source, role=None, catalog_warning=None, source=None, request_id=None, error_code=None)

Bases: MostlyrightError

The data’s source does not match the schema’s registered source, and the caller did not opt out via source_drift_reason. role (if set) identifies which leg of a pull_pairs request mismatched and uses the canonical long form: "observations" / "forecasts" / "settlement".

• Parameters:
  • message (str)
  • schema_source (str)
  • data_source (str)
  • role (str | None)
  • catalog_warning (str | None)
  • source (str | None)
  • request_id (str | None)
  • error_code (str)
• Return type: None

VALID_ROLES

Canonical role-name vocabulary for source mismatches.

catalog_warning: str | None

data_source: str

default_error_code: str

Subclass override — the stable string enum surfaced via error_code.

error_code: str

message: str

request_id: str | None

role: str | None

schema_source: str

source: str | None

exception mostlyright.core.exceptions.SourceUnavailableError(message=”, , source=None, http_status=None, retryable=False, retry_after_s=None, underlying=”, url=None, request_id=None, error_code=None)

Bases: MostlyrightError

A source (HTTP endpoint, vendored parser, etc.) returned an error or was otherwise unreachable. Carries enough metadata for callers to decide whether to retry and after how long.

• Parameters:
  • message (str)
  • source (str | None)
  • http_status (int | None)
  • retryable (bool)
  • retry_after_s (float | None)
  • underlying (str)
  • url (str | None)
  • request_id (str | None)
  • error_code (str)
• Return type: None

default_error_code: str

Subclass override — the stable string enum surfaced via error_code.

error_code: str

http_status: int | None

message: str

request_id: str | None

retry_after_s: float | None

retryable: bool

source: str | None

underlying: str

url: str | None

exception mostlyright.core.exceptions.StationOutOfGridError(message=”, , error_code=None, source=None, request_id=None)

Bases: SatelliteError

Station projection lands outside the product grid.

• Parameters:
  • message (str)
  • error_code (str)
  • source (str | None)
  • request_id (str | None)
• Return type: None

default_error_code: str

Subclass override — the stable string enum surfaced via error_code.

exception mostlyright.core.exceptions.StormNotFoundError(message=”, , query=”, active_storms=None, request_id=None, error_code=None)

Bases: NWPError

A HAFS storm query (id or name) doesn’t match any active storm.

Carries the query and the list of currently-active storm IDs so callers can present a useful error. Historical HAFS access requires passing the canonical storm_id directly (Storms() only knows currently-active storms).

• Parameters:
  • message (str)
  • query (str)
  • active_storms (list [str ])
  • request_id (str | None)
  • error_code (str)
• Return type: None

default_error_code: str

Subclass override — the stable string enum surfaced via error_code.

exception mostlyright.core.exceptions.TemporalDriftError(message=”, , schema_id, asserted_range, violating_rows, sample_violations=None, source=None, request_id=None, error_code=None)

Bases: MostlyrightError

Raised by the reproducibility audit when one or more rows have retrieved_at outside the asserted range AND fall within the volatile window of now. Indicates the source materially re-amended historical rows since the schema’s registered capture.

• Parameters:
  • message (str)
  • schema_id (str)
  • asserted_range (tuple [str , str ])
  • violating_rows (int)
  • sample_violations (list [dict [str , Any ] ])
  • source (str | None)
  • request_id (str | None)
  • error_code (str)
• Return type: None

asserted_range: tuple[str, str]

default_error_code: str

Subclass override — the stable string enum surfaced via error_code.

error_code: str

message: str

request_id: str | None

sample_violations: list[dict[str, Any]]

schema_id: str

source: str | None

violating_rows: int

exception mostlyright.core.exceptions.UnitsContractError(message=”, , error_code=None, source=None, request_id=None)

Bases: GOESDataCorruptError

NetCDF variable units attribute does not match the registry.

Subclass of GOESDataCorruptError. A per-variable units mismatch in _extract_from_dataset is recorded as a qc_status="suspect" row and the scan continues rather than aborting; this class remains importable for a genuinely unrecoverable case.

• Parameters:
  • message (str)
  • error_code (str)
  • source (str | None)
  • request_id (str | None)
• Return type: None

default_error_code: str

Subclass override — the stable string enum surfaced via error_code.

exception mostlyright.core.exceptions.UnsupportedResolutionError(message=”, , interval=None, supported=None, venue=None, field=None, expected=None, actual=None, location=None, doc_url=None, source=None, request_id=None, error_code=None)

Bases: ContractError

An interval= value is outside the venue’s supported resolution set.

The market-data price-history verbs take interval="1m" | "1h" | "1d"; a value the venue does not serve is a caller contract violation caught BEFORE any I/O, not a data-availability failure. The message names the venue’s valid set so the caller can fix the call without reading the venue’s docs; the same set is carried structurally in supported so an agent can branch on it without parsing prose:

try:
    df = markets.kalshi.candles(ticker, interval="5m", ...)
except UnsupportedResolutionError as e:
    print(e.venue, e.interval, e.supported)

Subclasses ContractError so existing except ContractError paths keep working — a caller that only wants “bad argument” granularity needs no change.

• Parameters:
  • message (str)
  • interval (str | None)
  • supported (list [str ] | None)
  • venue (str | None)
  • field (str | None)
  • expected (str | None)
  • actual (str | None)
  • location (str | None)
  • doc_url (str | None)
  • source (str | None)
  • request_id (str | None)
  • error_code (str)
• Return type: None

default_error_code: str

Subclass override — the stable string enum surfaced via error_code.

interval: str | None

The rejected interval= value exactly as the caller passed it.

supported: list[str] | None

The venue’s supported set, normalised to list[str] so the payload is JSON-stable regardless of the iterable handed in.

venue: str | None

The venue whose set was violated ("kalshi" / "polymarket").

exception mostlyright.core.exceptions.VenueCapabilityError(message=”, , venue=None, capability=None, remedy=None, field=None, expected=None, actual=None, location=None, doc_url=None, source=None, request_id=None, error_code=None)

Bases: ContractError

A verb exists in the shared venue grammar but this venue has no such concept.

The market-data verbs speak one grammar across venues, but the venues’ own hierarchies differ. Kalshi is Series -> Event -> Market; Polymarket is Event -> Market with no series tier at all. So markets.polymarket.series() exists (the grammar is shared and the absence must be discoverable) and RAISES this error teaching the venue difference plus the verb to use instead:

try:
    markets.polymarket.series()
except VenueCapabilityError as e:
    print(e.venue, e.capability, e.remedy)  # polymarket series use events()

This is a contract violation the caller fixes by calling a different verb — never a data-availability failure — so it is raised before any I/O and subclasses ContractError, keeping existing except ContractError paths working unchanged.

• Parameters:
  • message (str)
  • venue (str | None)
  • capability (str | None)
  • remedy (str | None)
  • field (str | None)
  • expected (str | None)
  • actual (str | None)
  • location (str | None)
  • doc_url (str | None)
  • source (str | None)
  • request_id (str | None)
  • error_code (str)
• Return type: None

capability: str | None

The grammar verb / concept the venue has no analog for ("series").

default_error_code: str

Subclass override — the stable string enum surfaced via error_code.

remedy: str | None

What to call instead ("use events()") — the teaching remedy.

venue: str | None

The venue lacking the capability ("polymarket" etc.).