langchain-ai/deepagents · error · ValueError

SubagentStop requires a materialized agent transcript path

Error message

SubagentStop requires a materialized agent transcript path

What it means

`_project_subagent_stop` builds the wire input for SubagentStop hooks and needs the path to the subagent's own transcript file. If `agent_transcript_path` is None — i.e. the subagent transcript was never materialized on disk — it raises `ValueError`, because the external hook process could not be given a transcript to inspect.

Source

Thrown at libs/code/deepagents_code/hooks/projection.py:304

    transcript_path: Path,
    _agent_transcript_path: Path | None,
) -> HookWireInput:
    return SubagentStartWireInput(
        **_base_fields(invocation, transcript_path, agent=event.agent),
        hook_event_name=HookEvent.SUBAGENT_START,
    )


@_project_event.register(SubagentStopEvent)
def _project_subagent_stop(
    event: SubagentStopEvent,
    invocation: HookInvocation,
    transcript_path: Path,
    agent_transcript_path: Path | None,
) -> HookWireInput:
    if agent_transcript_path is None:
        msg = "SubagentStop requires a materialized agent transcript path"
        raise ValueError(msg)
    return SubagentStopWireInput(
        **_base_fields(invocation, transcript_path, agent=event.agent),
        hook_event_name=HookEvent.SUBAGENT_STOP,
        stop_hook_active=event.continuation_count > 0,
        agent_transcript_path=str(agent_transcript_path),
        last_assistant_message=event.last_assistant_message,
        background_tasks=[
            BackgroundTaskWire.model_validate(task.model_dump())
            for task in event.background_tasks
        ],
        session_crons=[
            SessionCronWire.model_validate(cron.model_dump())
            for cron in event.session_crons
        ],
    )


def _base_fields(

View on GitHub (pinned to a1af029e6e)

Solutions

1. Ensure the subagent's transcript is materialized to disk before emitting SubagentStop and pass its path as `agent_transcript_path`
2. Check transcript-directory configuration/permissions so the transcript file can be written
3. If a subagent produced no transcript, skip projecting the SubagentStop hook rather than passing None

Example fix

// before
project_subagent_stop(event, invocation, transcript_path, None)
// after
agent_path = materialize_transcript(event.agent)  # e.g. Path('/tmp/agent-123.jsonl')
project_subagent_stop(event, invocation, transcript_path, agent_path)

if agent_transcript_path is None:
    raise ValueError("SubagentStop projection requires a materialized agent transcript")

def has_agent_transcript(p: Path | None) -> TypeGuard[Path]:
    return p is not None and p.exists()

try:
    wire = project_subagent_stop(event, invocation, transcript_path, agent_transcript_path)
except ValueError as e:
    logger.warning("skipping SubagentStop hook: %s", e)

When it happens

Trigger: Firing a SubagentStop hook projection while the caller (the hook runner/orchestrator) supplied `agent_transcript_path=None`, e.g. when the subagent never wrote a transcript file or the path failed to materialize before the stop event was processed.

Common situations: Subagent crashed or was cancelled before persisting its transcript; misconfigured transcript directory; a custom runner that invokes the projection layer without materializing agent transcripts.

Understand the failure class

Background: "Missing required field" and "field is required" errors: why libraries reject payloads that omit mandatory fields — this error's family across 20 libraries.

Related errors

• Unsupported notification type: {value}
• Unsupported hook event: {event}
• Could not parse embedded resource block. Block expected eith
• question text must not be blank
• choice has a blank 'value': {choice!r}

AI-assisted analysis of langchain-ai/deepagents@a1af029e6e (2026-08-29). Data as JSON: /api/errors/c9f49283eb556952. Report an issue: GitHub.