langchain-ai/langgraph · error · ValueError

'timeout' must be a non-negative number

Error message

'timeout' must be a non-negative number

What it means

Validation guard in the internal queue implementation: get()/put() argument validation rejects a negative timeout. The API follows queue.Queue semantics where timeout must be a non-negative number of seconds; passing a negative value is a caller bug rather than a runtime state problem.

Solutions

1. Pass a non-negative timeout or None.
2. Fix callers computing the timeout so they cannot go negative (e.g. max(0, deadline - now)).

When it happens

Trigger: Thrown at libs/langgraph/langgraph/_internal/_queue.py:100 when the library encounters an invalid state.

Common situations: See trigger scenarios.

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

AI-assisted analysis of langchain-ai/langgraph@38031739e5 (2026-08-26). Data as JSON: /api/errors/280168da6ee05571. Report an issue: GitHub.

Appendix: source

Thrown at libs/langgraph/langgraph/_internal/_queue.py:100

        The optional 'block' and 'timeout' arguments are ignored, as this method
        never blocks.  They are provided for compatibility with the Queue class.
        """
        self._queue.append(item)
        self._count.release()

    def get(self, block=False, timeout=None):
        """Remove and return an item from the queue.

        If optional args 'block' is true and 'timeout' is None (the default),
        block if necessary until an item is available. If 'timeout' is
        a non-negative number, it blocks at most 'timeout' seconds and raises
        the Empty exception if no item was available within that time.
        Otherwise ('block' is false), return an item if one is immediately
        available, else raise the Empty exception ('timeout' is ignored
        in that case).
        """
        if timeout is not None and timeout < 0:
            raise ValueError("'timeout' must be a non-negative number")
        if not self._count.acquire(block, timeout):
            raise queue.Empty
        try:
            return self._queue.popleft()
        except IndexError:
            raise queue.Empty

    def wait(self, block=True, timeout=None):
        """If queue is empty, wait until an item maybe is available,
        but don't consume it.
        """
        if timeout is not None and timeout < 0:
            raise ValueError("'timeout' must be a non-negative number")
        self._count.wait(block, timeout)

    def empty(self):
        """Return True if the queue is empty, False otherwise (not reliable!)."""
        return len(self._queue) == 0

View on GitHub (pinned to 38031739e5)