Skip to content

[BUG] TS Graph: a node interrupt while other ready nodes sit unscheduled in targets deadlocks graph.invoke() forever on queue.wait() #5066

Open

Description

@BlueX888

Checks

  • I have updated to the lastest minor and patch version of Strands
  • I have checked the documentation and this is not expected behavior
  • I have searched ./issues and there are no duplicates of my issue

SDK Language

TypeScript

Strands Version

@strands-agents/sdk 0.0.1-development — checkout of main at 38afb968e1f40aa47546ead09a22ec031bd345de

Language Runtime Version

Node.js v22.23.2

Operating System

macOS (Darwin 25.6.0)

Installation Method

git clone

Steps to Reproduce

In Graph._stream (strands-ts/src/multiagent/graph.ts), when a node result with status INTERRUPTED is processed while the targets array still holds discovered-but-unscheduled nodes, the run deadlocks: scheduling is gated on !interrupted, streams is empty, and the loop blocks forever on queue.wait() with no producer.

This is reachable whenever targets is non-empty at the moment the interrupt is observed — e.g. with a bounded maxConcurrency (a validated config, graph.ts:592-593) where not all sources fit in flight at once, or when a completion earlier in the same queue-drain pass has already added ready nodes to targets.

Minimal reproduction (no network; plain Node subclasses). Save as strands-ts/src/multiagent/__tests__/zz-repro-graph-interrupt-deadlock.test.ts and run with npx vitest run --project unit-node src/multiagent/__tests__/zz-repro-graph-interrupt-deadlock.test.ts inside strands-ts/:

import { describe, expect, it } from 'vitest'
import { Graph } from '../graph.js'
import { Node } from '../nodes.js'
import { Status } from '../state.js'
import { TextBlock } from '../../types/messages.js'
import { Interrupt } from '../../interrupt.js'
import type { NodeResultUpdate } from '../state.js'
import type { MultiAgentInput } from '../multiagent.js'
import type { MultiAgentState } from '../state.js'
import type { MultiAgentStreamEvent } from '../events.js'
import type { NodeInputOptions } from '../nodes.js'

class StubNode extends Node {
  private readonly _update: NodeResultUpdate

  constructor(id: string, update: NodeResultUpdate) {
    super(id, {})
    this._update = update
  }

  async *handle(
    _input: MultiAgentInput,
    _state: MultiAgentState,
    _options?: NodeInputOptions
  ): AsyncGenerator<MultiAgentStreamEvent, NodeResultUpdate, undefined> {
    return this._update
  }
}

function withTimeout<T>(promise: Promise<T>, ms: number, label: string): Promise<T> {
  return Promise.race([
    promise.then(
      (value) => value,
      (error) => {
        throw error
      }
    ),
    new Promise<T>((_, reject) => setTimeout(() => reject(new Error(`TIMEOUT after ${ms}ms: ${label}`)), ms)),
  ])
}

describe('zz-repro: graph deadlock when interrupt leaves queued targets', () => {
  it('terminates with an INTERRUPTED result instead of hanging', async () => {
    const a = new StubNode('A', { content: [new TextBlock('done-a')] })
    const b = new StubNode('B', {
      content: [new TextBlock('needs-approval')],
      interrupts: [new Interrupt({ id: 'int-1', name: 'approval', reason: 'need approval' })],
    })
    const c = new StubNode('C', { content: [new TextBlock('done-c')] })

    const graph = new Graph({
      nodes: [a, b, c],
      edges: [['A', 'C']],
      sources: ['A', 'B'],
      maxConcurrency: 1,
      // No timeout on purpose: the default config must still terminate on interrupt.
    })

    const result = await withTimeout(graph.invoke('go'), 3000, 'graph.invoke never settled (deadlock)')
    expect(result.status).toBe(Status.INTERRUPTED)
  }, 20000)

  it('control: same graph with no interrupt settles fine', async () => {
    const a = new StubNode('A', { content: [new TextBlock('done-a')] })
    const b = new StubNode('B', { content: [new TextBlock('done-b')] })
    const c = new StubNode('C', { content: [new TextBlock('done-c')] })

    const graph = new Graph({
      nodes: [a, b, c],
      edges: [['A', 'C']],
      sources: ['A', 'B'],
      maxConcurrency: 1,
    })

    const result = await withTimeout(graph.invoke('go'), 3000, 'control graph hung')
    expect(result.status).toBe(Status.COMPLETED)
  }, 20000)
})

A → C is the only edge, so when A completes it makes C ready; with maxConcurrency: 1 the interrupting node B is in flight while C sits in targets. B's INTERRUPTED result sets the interrupted flag, C is never scheduled, and queue.wait() has no producers left.

Expected Behavior

graph.invoke() should settle with a MultiAgentResult whose status is INTERRUPTED (here C is simply left unrun), so the run ends and can be resumed with graph.invoke(responses).

Basis:

  • The _pendingInterruptState field documents this contract (strands-ts/src/multiagent/graph.ts:151-155): "State retained across invocations when a run ends INTERRUPTED. Lets graph.invoke(responses) resume on the same instance ... Cleared when a run terminates in any non-INTERRUPTED state." An interrupted run is expected to END so it can be resumed.
  • The loop's own comment (graph.ts:401-402): "Stop scheduling new nodes once any node has interrupted; in-flight siblings run to completion on their own." — the run is meant to end after in-flight siblings drain, with unscheduled targets abandoned, not to keep waiting on them.
  • Node.handle results carry Status.INTERRUPTED when the update has interrupts (strands-ts/src/multiagent/nodes.ts:113) precisely so the orchestrator can surface the interrupt.
  • The repo's own test already enforces settle-on-interrupt for the in-flight-siblings shape (strands-ts/src/multiagent/__tests__/interrupts.test.ts:250-254, "Graph parallel: interrupt on one branch lets in-flight sibling finish"): const result = await graph.invoke('begin') ... expect(result.status).toBe(Status.INTERRUPTED).

Actual Behavior

Verbatim output of the reproduction above, on main @ 38afb968e1f40aa47546ead09a22ec031bd345de (observed identically by two independent verification runs, and re-run locally with the same result):

❯ |unit-node| src/multiagent/__tests__/zz-repro-graph-interrupt-deadlock.test.ts (2 tests | 1 failed) 9012ms
 × terminates with an INTERRUPTED result instead of hanging 9009ms (retry x2)
 ✓ control: same graph with no interrupt settles fine 2ms
Error: TIMEOUT after 3000ms: graph.invoke never settled (deadlock)
 Test Files  1 failed (1)
      Tests  1 failed | 1 passed (2)

graph.invoke() never settles: no MultiAgentResult is produced, _pendingInterruptState is never stashed, so the interrupt cannot be surfaced or resumed. The control test (identical graph without the interrupt) passes, isolating the interrupt path as the cause. An independent reproduction with real Agent nodes whose tool calls context.interrupt() (the strands HumanInTheLoop vended intervention) shows the same hang, so this is not an artifact of stub nodes. Notably, a configured graph timeout cannot break the hang either — the timeout/abort check at the top of the loop (graph.ts:339) is never re-evaluated while blocked in queue.wait().

Possible Solution

Root cause: once an INTERRUPTED node result sets interrupted = true (strands-ts/src/multiagent/graph.ts:404), the scheduling loop is gated on !interrupted (graph.ts:345), so entries left in targets are never scheduled — but the outer loop condition still counts them as pending work (graph.ts:338), so with streams empty the loop blocks forever on await queue.wait() (graph.ts:376), which only resolves when an entry is available (strands-ts/src/queue.ts:57-59) and no producer task is running.

Fix: terminate the loop once interrupted — e.g. if (interrupted) break at the top of the outer while loop, or tighten the condition to (!interrupted && targets.length > 0) || streams.size > 0 — so the run ends with the INTERRUPTED MultiAgentResult and stashes _pendingInterruptState; leftover targets are then recomputed on resume via _findResumeTargets, and the existing interrupts tests keep passing.

I'm happy to open a PR with this fix plus a regression test mirroring the reproduction above if that works for the maintainers.

Additional Context

Additional verbatim evidence from the second verification run
npx vitest run --project unit-node src/multiagent/__tests__/zz-repro-graph-interrupt-deadlock.test.ts
× terminates with an INTERRUPTED result instead of hanging 9011ms (retry x2)
✓ control: same graph with no interrupt settles fine 2ms
Error: TIMEOUT after 3000ms: graph.invoke never settled (deadlock)
(own repro, different shape) × real Agent nodes: tool calling context.interrupt deadlocks the sibling still in targets 7511ms (retry x2)
(own repro) × even a configured graph timeout cannot break the hang — DEADLOCK: graph timeout=300ms did not fire; invoke still hung at 2500ms

The last two lines are from the same run's additional probes: one with real Agent nodes driving the interrupt through a tool, one with a configured graph timeout of 300ms — neither settles.

AI usage disclosure

This issue was drafted with AI assistance; the reproduction output quoted under "Actual Behavior" is the verbatim console output of two independent automated verification runs of the script above, and I re-ran the same command locally with the same result and verified the quoted source lines against main @ 38afb968e1f40aa47546ead09a22ec031bd345de. Per the template, "Human Overview" is intentionally left blank for a human to fill in.

Related Issues

None found — searches of this repository's issues and PRs for this symptom (graph interrupt deadlock, graph hang, graph invoke, multiagent interrupt, maxConcurrency, deadlock) returned no duplicates. Nearest neighbors, neither of which matches: #4419 / #4753 (graph reports COMPLETED when a child stream raises CancelledError — a wrong-status bug on the cancel path, not an interrupt) and #2449 (feature request for nested multi-agent interrupt support). No open PR addresses this loop.

Activity

  1. BlueX888 commented on Oct 11, 2026

    @BlueX888
    ContributorAuthor

    Reproduced this. Root cause: strands-ts/src/multiagent/graph.ts:404 — once an INTERRUPTED node result sets interrupted = true, the scheduling gate (!interrupted, graph.ts:345) never drains the remaining targets while the loop condition (graph.ts:338) still counts them as pending, so with no streams in flight the loop blocks forever on await queue.wait() (graph.ts:376) with no producer.

    Minimal reproduction:

    npx vitest run --project unit-node src/multiagent/__tests__/zz-repro-graph-interrupt-deadlock.test.ts (inside strands-ts/; repro test file per issue body)
    

    Observed output:

    ❯ |unit-node| src/multiagent/__tests__/zz-repro-graph-interrupt-deadlock.test.ts (2 tests | 1 failed) 9012ms
     × terminates with an INTERRUPTED result instead of hanging 9009ms (retry x2)
     ✓ control: same graph with no interrupt settles fine 2ms
    Error: TIMEOUT after 3000ms: graph.invoke never settled (deadlock)
     Test Files  1 failed (1)
          Tests  1 failed | 1 passed (2)
    

    Happy to open a PR with this fix, or to be assigned if you prefer to take it.

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

    area-hilHuman in the loop and suspend/resumearea-multiagentMulti-agent relatedbugSomething isn't workingtypescriptPull requests that update typescript code

    Type

    Fields

    Language

    TypeScript

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions