Skip to content

bug(server): an AdcpError raised by a pre-validation hook reaches the buyer as INVALID_REQUEST #1278

Closed

Description

@bokelley

Summary

On 8.0.0, an AdcpError raised by a pre-validation hook reaches the buyer as INVALID_REQUEST. Its code, field, recovery and details are lost, and the original error is stringified into the message.

_apply_pre_validation_hooks (adcp/server/_hooks.py:89-96) wraps any exception in PreValidationHookError. The dispatcher (adcp/server/mcp_tools.py:3163-3172) then turns every PreValidationHookError into Error(code="INVALID_REQUEST", message=str(exc)).

Reproduction (adcp 8.0.0)

import asyncio

from adcp.decisioning import AdcpError
from adcp.server import ADCPHandler
from adcp.server.mcp_tools import create_tool_caller


class Seller(ADCPHandler):
    async def get_products(self, params, context=None):
        return {"products": []}


def require_release_version(tool_name, params):
    raise AdcpError("VERSION_UNSUPPORTED", message="adcp_version is required",
                    recovery="correctable", field="adcp_version")


async def main():
    call = create_tool_caller(Seller(), "get_products", pre_validation_hook=require_release_version)
    try:
        await call({"buying_mode": "brief", "brief": "video"})
    except Exception as exc:
        for error in exc.errors:
            print(error.code, "|", error.message, "|", error.field)

asyncio.run(main())

Output:

INVALID_REQUEST | pre_validation_hook[0] require_release_version raised AdcpError: AdcpError[VERSION_UNSUPPORTED / correctable]: adcp_version is required | None

Why an adopter hits this

A pre-validation hook is the natural place for request-envelope policy that must run before schema validation, such as requiring an explicit adcp_version. Hooks run before detect_wire_version, so this is also the only point where a seller can reject a request that omits the version, instead of letting it default.

Embedded Sales Agent does exactly this. Buyers that omit adcp_version, or send one ESA doesn't serve, are meant to get VERSION_UNSUPPORTED with field="adcp_version". They get INVALID_REQUEST with no field. A buyer that branches on the error code cannot tell a version-negotiation failure from a malformed request, and so cannot retry with a supported version.

Suggested fix

When the hook's exception is an AdcpError (or ADCPTaskError), re-raise it with its own code, field, recovery and details. Keep the INVALID_REQUEST wrapping for any other exception type, which is a hook bug rather than a deliberate rejection.

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 (no matching label in repo — gap noted)
    Status: ready-to-implement
    Milestone: (omitted — none named)

    What the experts said:

    • code-reviewer: Confirmed bug; fix belongs in mcp_tools.py except PreValidationHookError block (inspect exc.__cause__), NOT _hooks.py — that module must remain stdlib-only per its module docstring; also flagged that the existing test must be split.
    • dx-expert: Confirmed bug and correct API design — AdcpError is the natural signal for policy rejections from hooks; non-AdcpError exceptions should still wrap as INVALID_REQUEST; docs/docstring update needed.

    My take: Both experts agree the bug is real and the fix is clear. The correct fix location is src/adcp/server/mcp_tools.py lines 3163–3172 (not _hooks.py, which is constrained to stdlib). The existing AdcpError handler in serve.py will project the structured error correctly once it's no longer swallowed.

    Implementation scope:

    • Fix: src/adcp/server/mcp_tools.py — in except PreValidationHookError as exc block, inspect exc.__cause__; if it is ADCPError (from adcp.exceptions) or a decisioning AdcpError (via the existing _get_decisioning_adcp_error_types() helper in serve.py), re-raise it directly. Both types already have correct projection handlers in serve.py. Keep wrapping all other exception causes as INVALID_REQUEST.
    • Tests: tests/test_pre_validation_hooks.py — split test_hook_exception_surfaces_as_invalid_request into (a) ValueError/RuntimeError → INVALID_REQUEST (existing path) and (b) AdcpError(code="VERSION_UNSUPPORTED", field="adcp_version") → structured error with code="VERSION_UNSUPPORTED" and field="adcp_version" preserved.
    • Docstring: src/adcp/server/_hooks.py _apply_pre_validation_hooks docstring says "A hook that raises... is wrapped in PreValidationHookError" — still accurate since AdcpError is re-raised before it reaches the wrap; no change needed there. But add a note that AdcpError/ADCPTaskError raised by hooks propagates unmodified.
    • Non-breaking rationale: Hooks raising AdcpError were getting incorrect behavior (INVALID_REQUEST); fixing to the intended structured code is a bug fix. Hooks raising any other exception type continue to produce INVALID_REQUEST unchanged.

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


    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