Skip to content

[Bug]: RuntimeError: threads can only be started once - Celery worker compatibility issue in fnllm utils #1974

@droideronline

Description

@droideronline

Do you need to file an issue?

  • I have searched the existing issues and this bug is not already filed.
  • My model is hosted on OpenAI or Azure. If not, please look at the "model providers" issue and don't file a new one here.
  • I believe this is a legitimate bug, not just a question. If this is a question, please use the Discussions area.

Describe the bug

Description:

GraphRAG fails in Celery worker processes with RuntimeError: threads can only be started once when executing queries that use embedding models.

Root Cause

The run_coroutine_sync() function in graphrag/language_model/providers/fnllm/utils.py is not fork-safe. When Celery creates worker processes by forking:

  1. Process Fork: Celery forks the main process to create workers
  2. Thread Inheritance: Child processes inherit parent's global thread objects (_thr, _loop, _pid)
  3. Dead Threads: Inherited thread objects exist but the actual threads are not running
  4. Restart Failure: Code attempts to call _thr.start() on a dead thread object
  5. Runtime Error: Python raises "threads can only be started once" because threads have single-use lifecycle

Additional Files to Reference:

  • graphrag/language_model/providers/fnllm/utils.py (lines 112-134)
  • graphrag/language_model/providers/fnllm/models.py (where run_coroutine_sync is called)

Impact:

  • GraphRAG queries fail in Celery workers
  • Any async operation using FNLLM models crashes
  • Production deployments using Celery are broken

Steps to reproduce

Expected Behavior

No response

GraphRAG Config Used

No Changes in Config

Logs and screenshots

No response

Additional Information

  • GraphRAG Version: 2.3.0
  • Operating System: Windows
  • Python Version: 3.11
  • Related Issues:

Metadata

Metadata

Assignees

No one assigned

    Labels

    backlogWe've confirmed some action is needed on this and will plan itbugSomething isn't workingv3Issues that we know should be closed with the v3 release in late 2025.

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions