Skip to content

bug(reporting): Core install() lets service exceptions reach buyers as INTERNAL_ERROR / terminal #1292

Closed

Description

@bokelley

Summary

On 8.0.0, ReliableReportingService raises plain Python exceptions from its buyer-facing methods:

  • ReliableReportingUnavailableError(RuntimeError) (adcp/reporting/service_lifecycle.py:42-45)
  • ReliableReportingConfigurationError(ValueError) (adcp/reporting/service.py:95-96)
  • LedgerConflictError(RuntimeError), which carries a .code (adcp/reporting/ledger/store.py:107-117)

When the service is mounted on a DecisioningPlatform with install(), the ReportingInstallMixin methods (service.py:1269-1291) call the service without translating these. The dispatcher then wraps them as INTERNAL_ERROR with recovery="terminal" (adcp/decisioning/dispatch.py:1647-1671). A buyer told "terminal" stops retrying, even when the cause is a restart (SERVICE_UNAVAILABLE, transient) or its own bad cursor (correctable).

The managed-production composition already does this mapping. ReportingProductionHandler turns LedgerConflictError into ADCPTaskError(code=error.code) for sync_accounts, sync_reporting_status and get_media_buy_delivery (adcp/reporting/production/handler.py:256-265, 286-290, 411-417). The Core path has no equivalent.

Reproduction (adcp 8.0.0)

import asyncio
import logging
import warnings

warnings.simplefilter("ignore")
logging.disable(logging.CRITICAL)

from adcp.decisioning import DecisioningCapabilities, DecisioningPlatform, SingletonAccounts
from adcp.decisioning.serve import create_adcp_server_from_platform
from adcp.reporting import ReliableReportingService
from adcp.reporting.ledger.store import encode_cursor
from adcp.server.auth import current_principal
from adcp.server.base import ToolContext
from adcp.types import GetMediaBuyDeliveryRequest, GetReportingStatusRequest


class Seller(DecisioningPlatform):
    capabilities = DecisioningCapabilities(specialisms=["sales-non-guaranteed"], supported_billing=["operator"])
    accounts = SingletonAccounts(account_id="acct")

    def get_products(self, req, ctx): return {"products": []}
    def create_media_buy(self, req, ctx): raise NotImplementedError
    def update_media_buy(self, media_buy_id, patch, ctx): raise NotImplementedError
    def sync_creatives(self, req, ctx): raise NotImplementedError
    def get_media_buy_delivery(self, req, ctx): raise NotImplementedError


service = ReliableReportingService.memory(account_context=lambda c: None)
handler, _, _ = create_adcp_server_from_platform(service.install(Seller()))


async def show(label, call):
    try:
        await call
    except Exception as exc:
        print(f"{label}: {exc.code} / {exc.recovery} / caused_by={type(exc.__cause__).__name__}")


async def main():
    status = GetReportingStatusRequest.model_validate({"account": {"account_id": "acct"}, "view": "summary"})
    await show("not started", handler.get_reporting_status(status, ToolContext()))

    await service.start()
    # No authenticated principal -> default caller resolution refuses.
    await show("no caller  ", handler.get_reporting_status(status, ToolContext()))
    # Authenticated exact revision read with a cursor minted for another revision.
    current_principal.set("buyer-1")
    delivery = GetMediaBuyDeliveryRequest.model_validate({
        "account": {"account_id": "acct"},
        "reporting_revision_id": "rev_a",
        "pagination": {"cursor": encode_cursor({"revision": "rev_b"})},
    })
    await show("bad cursor ", handler.get_media_buy_delivery(delivery, ToolContext()))
    await service.close()

asyncio.run(main())

Output:

not started: INTERNAL_ERROR / terminal / caused_by=ReliableReportingUnavailableError
no caller  : INTERNAL_ERROR / terminal / caused_by=ReliableReportingConfigurationError
bad cursor : INTERNAL_ERROR / terminal / caused_by=LedgerConflictError

Why an adopter hits this

Embedded Sales Agent mounts the service on its LazyPlatformRouter with install(). It subclasses the service (SalesagentReportingService in core/reporting.py) only to wrap get_reporting_status, sync_reporting_status and get_revision_content in _serve. _serve maps unavailable to SERVICE_UNAVAILABLE/transient, LedgerConflictError to its own code/correctable, and configuration errors to INVALID_REQUEST. That is about 40 LOC. Without it, every reporting call made while the service starts, restarts or fails tells the buyer to give up.

Ask

Translate in the SDK, so every composition gets the same wire errors:

  1. In the install() mixin (or the service's public methods), map ReliableReportingUnavailableError to AdcpError("SERVICE_UNAVAILABLE", recovery="transient") and LedgerConflictError to AdcpError(error.code, recovery="correctable"), matching ReportingProductionHandler.
  2. Split ReliableReportingConfigurationError into request-time refusals, which are buyer-visible (AUTH_REQUIRED / INVALID_REQUEST), and composition errors, which stay INTERNAL_ERROR. Today one class covers both a missing caller and a misconfigured service.

Activity

  1. added
    bugSomething isn't working
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on Oct 2, 2026
  2. bokelley commented on Oct 2, 2026

    @bokelley
    ContributorAuthor

    Triage

    Classification: Bug
    Bucket(s): handlers (label gap — handlers label does not exist in this repo)
    Status: ready-to-implement
    Milestone: (omitted — no target version named)

    What the experts said:

    • code-reviewer: converges — adding try/except translation in the four ReportingInstallMixin methods mirrors what ReportingProductionHandler already does; non-breaking because adopters never call these methods directly (the dispatcher does), and the wire-level change from INTERNAL_ERROR/terminal to SERVICE_UNAVAILABLE/transient is the correct behavior.
    • dx-expert: converges — fix is transparent to adopters; no call-site changes needed; adding a kind attribute to ReliableReportingConfigurationError is the clean way to split the two cases without widening the public API surface.

    My take: The bug is clear and well-characterized — three exception types escape the ReportingInstallMixin without translation, producing INTERNAL_ERROR/terminal where buyers should get a recoverable error. The production handler already contains the correct mapping; this PR brings the Core path into alignment.

    Implementation scope:

    • src/adcp/reporting/service.py — add kind: Literal["misconfiguration", "caller_unavailable"] = "misconfiguration" to ReliableReportingConfigurationError (line ~95); update the two runtime raise sites (lines ~1074 and ~1091 in _sync_reporting_status / _sync_reporting_receipts) to pass kind="caller_unavailable"; wrap each of the four ReportingInstallMixin methods (lines 1269–1291) with:
      except ReliableReportingUnavailableError:
          raise <AdcpError("SERVICE_UNAVAILABLE", recovery="transient")>
      except LedgerConflictError as e:
          raise <AdcpError(e.code, recovery="correctable")>
      except ReliableReportingConfigurationError as e:
          if e.kind == "caller_unavailable":
              raise <AdcpError("SERVICE_UNAVAILABLE", recovery="transient")>
          raise  # misconfiguration stays INTERNAL_ERROR/terminal
      Only wrap the await service.<method>(...) branch in sync_reporting_status and sync_reporting_receipts — leave the super() fallback paths unaffected.
    • No changes needed to service_lifecycle.py, ledger/store.py, production/handler.py, or dispatch.py.
    • Tests — add coverage for all three translation paths through install(): unavailable → SERVICE_UNAVAILABLE/transient, ledger conflict → error.code/correctable, caller-unavailable configuration error → SERVICE_UNAVAILABLE/transient, and misconfiguration-kind still → INTERNAL_ERROR/terminal. The issue's reproduction script is a ready-made basis. Zero existing test coverage for ReportingInstallMixin exists, so this adds a new test file or extends tests/reporting/.
    • Required checks: pytest on reporting subset, mypy src/, ruff check . / black --check .
    • Non-breaking rationale: the mixin methods are called internally by the dispatcher, not by adopters. ReliableReportingConfigurationError.kind is a new attribute with a default; all existing isinstance checks and the configuration_error=ReliableReportingConfigurationError reference in _compose_production are unaffected.

    Triaged by Claude Code. Session: https://claude.ai/code/session_014bgQL6e8jr5wcfoPhTER7b


    Generated by Claude Code

  3. added and removed
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on Oct 2, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions