What causes "AGENT_DELEGATION_HOOK_FAILED" in mastra-ai/mastra?

Fix the code inside the sub-agent's `onDelegationStart` hook so it does not throw (the wrapped hookError message identifies the root cause)

mastra-ai/mastra · error · MastraError

AGENT_DELEGATION_HOOK_FAILED

AGENT_DELEGATION_HOOK_FAILED

Error message

AGENT_DELEGATION_HOOK_FAILED

What it means

A MastraError (id AGENT_DELEGATION_HOOK_FAILED) thrown when a sub-agent's `onDelegationStart` hook throws AND the agent's hook error strategy is configured to 'throw' (fail-closed). Because the delegation never started, the error is raised directly instead of routing through `onDelegationComplete`. With a non-throw strategy the hook error is only logged and delegation proceeds.

Source

Thrown at packages/core/src/agent/agent.ts:5010

            // failure, so the failure path never re-invokes it.
            let completeHookInvoked = false;

            // Call onDelegationStart before resolving the sub-agent's runtime
            // config so mutations of the delegated run's context in the hook
            // are visible to version, model, and default-options resolution
            // below. Rejection handling happens after resolution because the
            // rejection path needs the resolved model version and memory config.
            let startResult: DelegationStartResult | void | undefined;
            if (delegation?.onDelegationStart) {
              try {
                startResult = await delegation.onDelegationStart(delegationStartContext);
              } catch (hookError) {
                const error = recordHookError('onDelegationStart', hookError, 'onDelegationStart hook error');
                // Fail closed when configured: the delegation never started, so
                // this throws directly rather than routing through
                // onDelegationComplete. Otherwise continue with original values.
                if (hookErrorStrategy === 'throw') {
                  throw new MastraError(
                    {
                      id: 'AGENT_DELEGATION_HOOK_FAILED',
                      domain: ErrorDomain.AGENT,
                      category: ErrorCategory.USER,
                      details: {
                        agentName: this.name,
                        subAgentName: agent.name ?? agent.id,
                        hook: 'onDelegationStart',
                        runId: runId || '',
                      },
                    },
                    error,
                  );
                }
              }
            }

            // Resolve versioned sub-agent if a version override exists on the

View on GitHub (pinned to 75dd419e61)

Solutions

Fix the code inside the sub-agent's `onDelegationStart` hook so it does not throw (the wrapped hookError message identifies the root cause)
Set the hook error strategy to a non-throwing value (e.g. 'continue'/'log') if a failed hook should not abort delegation
Add try/catch inside the hook to swallow/log non-critical failures
Validate any requestContext values the hook reads are provided for delegation calls

Example fix

// before
hooks: { onDelegationStart: async (ctx) => { await auditService.log(ctx); } }
// after
hooks: { onDelegationStart: async (ctx) => { try { await auditService.log(ctx); } catch (e) { logger.warn('audit failed', e); } } }

Defensive patterns

Strategy: try-catch

Type guard

function isDelegationHookError(e) {
  return e instanceof Error && 'id' in e && e.id === 'AGENT_DELEGATION_HOOK_FAILED';
}

Try / catch

try {
  await networkDelegate(...);
} catch (e) {
  if (e?.id === 'AGENT_DELEGATION_HOOK_FAILED') {
    logger.error('delegation blocked by onDelegationStart hook', e.details);
    return { status: 'delegation-blocked' };
  }
  throw e;
}

Prevention

Wrap hook bodies in try/catch and log instead of throwing for non-critical failures
Only use hookErrorStrategy 'throw' when failing the delegation is truly required
Ensure hooks don't assume requestContext fields absent during delegation calls
Monitor hook errors to catch broken audit/telemetry dependencies early

When it happens

Trigger: Multi-agent (network/delegation) invocation where a sub-agent has an `onDelegationStart` lifecycle hook registered, the hook callback throws, and hookErrorStrategy === 'throw' on the delegation configuration.

Common situations: Hooks that call external audit/telemetry services which are unreachable; hooks referencing request context fields that are absent in delegation calls; typo'd or version-mismatched hook signatures causing a TypeError inside the hook.

Related errors

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/f7c360548c044af0. Report an issue: GitHub.