langflow-ai/langflow · critical · RuntimeError

Refusing to start with {num_workers} workers and the default

Error message

Refusing to start with {num_workers} workers and the default in-memory job queue. POLLING and STREAMING event delivery fail with 'Job not found' roughly half the time because the build queue lives in one worker's memory and the follow-up GET /api/v1/build/<job_id>/events request lands on a different worker. Pick one of:
  * Configure a shared job queue: LANGFLOW_JOB_QUEUE_TYPE=redis. Works for every event_delivery mode.
  * Run with --workers 1. Single worker, no cross-worker routing.
Note: event_delivery=direct works in multi-worker because the POST endpoint streams events back inline, but every client must opt into direct delivery; the server cannot enforce that at startup.

What it means

At startup, langflow run refuses (RuntimeError via ensure_multi_worker_safe) to launch with more than one worker while the default in-memory job queue is active. Build jobs would live in one worker's memory, and follow-up GET /api/v1/build/<job_id>/events requests would land on other workers, producing intermittent 'Job not found' failures for POLLING and STREAMING delivery. The fail-fast check replaces a heisenbug with a clear configuration error.

Source

Thrown at src/backend/base/langflow/__main__.py:267

    """
    if num_workers <= 1:
        return
    if get_settings_service().settings.job_queue_type == "redis":
        return
    msg = (
        f"Refusing to start with {num_workers} workers and the default in-memory "
        "job queue. POLLING and STREAMING event delivery fail with 'Job not found' "
        "roughly half the time because the build queue lives in one worker's "
        "memory and the follow-up GET /api/v1/build/<job_id>/events request lands "
        "on a different worker. Pick one of:\n"
        "  * Configure a shared job queue: LANGFLOW_JOB_QUEUE_TYPE=redis. Works "
        "for every event_delivery mode.\n"
        "  * Run with --workers 1. Single worker, no cross-worker routing.\n"
        "Note: event_delivery=direct works in multi-worker because the POST "
        "endpoint streams events back inline, but every client must opt into "
        "direct delivery; the server cannot enforce that at startup."
    )
    raise RuntimeError(msg)


def display_results(results) -> None:
    """Display the results of the migration."""
    for table_results in results:
        table = Table(title=f"Migration {table_results.table_name}")
        table.add_column("Name")
        table.add_column("Type")
        table.add_column("Status")

        for result in table_results.results:
            status = "Success" if result.success else "Failure"
            color = "green" if result.success else "red"
            table.add_row(result.name, result.type, f"[{color}]{status}[/{color}]")

        console.print(table)
        console.print()  # Print a new line

View on GitHub (pinned to 976ec789d2)

Solutions

1. Configure a shared queue: set LANGFLOW_JOB_QUEUE_TYPE=redis (with a reachable Redis) — works for every event_delivery mode.
2. Or run single-worker: 'langflow run --workers 1'.
3. If all clients opt into event_delivery=direct, multi-worker is functionally safe, but the server still cannot verify client behavior — prefer one of the two supported configs above.

Example fix

# before
langflow run --workers 4  # RuntimeError: Refusing to start with 4 workers and the default in-memory job queue
# after (option A: shared queue)
LANGFLOW_JOB_QUEUE_TYPE=redis langflow run --workers 4
# after (option B: single worker)
langflow run --workers 1

import os
workers = int(os.environ.get("LANGFLOW_WORKERS", "1"))
queue = os.environ.get("LANGFLOW_JOB_QUEUE_TYPE", "memory")
if workers > 1 and queue != "redis":
    raise SystemExit("Set LANGFLOW_JOB_QUEUE_TYPE=redis or use --workers 1")

When it happens

Trigger: langflow run --workers 4 (or LANGFLOW_WORKERS>1) without LANGFLOW_JOB_QUEUE_TYPE=redis; deploying multi-worker behind a load balancer with the default in-memory queue.

Common situations: Scaling up workers in production for CPU capacity; copying a single-worker dev config to a multi-worker container orchestration; setting workers via env var while forgetting the queue type.

Related errors

• str(e)
• Job not found: {exc!s}
• Job not found: {exc!s}
• Failed to download files: ${response.statusText}
• Failed to delete MCP Server

AI-assisted analysis of langflow-ai/langflow@976ec789d2 (2026-08-14). Data as JSON: /api/errors/7a1727451cbd705d. Report an issue: GitHub.