Instance <Document at 0x7f72c31c0980> is not bound to a Session; attribute refresh operation cannot proceed (Background on this error at: https://sqlalche.me/e/20/bhk3)Help

[Jekie1]

Self Checks

• I have searched for existing issues search for existing issues, including closed ones.
• I confirm that I am using English to submit this report (我已阅读并同意 Language Policy).
• [FOR CHINESE USERS] 请务必使用英文提交 Issue，否则会被关闭。谢谢！:)
• Please do not modify this template :) and fill in all the required fields.

1. Is this request related to a challenge you're experiencing? Tell me about your story.

Why does uploading files using a pipeline-style knowledge base cause an error: Instance <Document at 0x7f72c31c0980> is not bound to a Session; attribute refresh operation cannot proceed (Background on this error at: https://sqlalche.me/e/20/bhk3)? What should I do? This problem has been ongoing for a long time.

2. Additional context or comments

Instance <Document at 0x7f72c31c0980> is not bound to a Session; attribute refresh operation cannot proceed (Background on this error at: https://sqlalche.me/e/20/bhk3)

[dosubot[bot]]

This error happens because a Document ORM object is being accessed outside an active SQLAlchemy session—usually after being passed between pipeline nodes, threads, or tasks, which causes it to become detached. This is a known issue in Dify's pipeline-based document parsing and indexing workflows. Legacy (non-pipeline) indexing works because it keeps the session context intact, but pipelines can lose session context between steps, triggering this error.

The official fix is to only pass primary key IDs (not ORM objects) between pipeline steps and always re-query the Document inside each node or task using a new session. This pattern is implemented in the feat/rag-2 branch and PR #26480, and is included in Dify 2.0.0 beta and later. Upgrading to 2.0.0 beta or newer will resolve this issue for most users. Downgrading does not help, as the problem exists in 1.9.0 and 1.9.1 as well [discussion].

If you cannot upgrade, a temporary workaround is to modify your pipeline or custom node code to avoid passing ORM objects directly—pass only IDs and re-query the object inside the node using a new session, for example:

# Bad: passing ORM object
def node_func(document: Document):
    print(document.id)  # document may be detached

# Good: passing only ID and re-querying
def node_func(document_id: int):
    with Session(engine) as session:
        document = session.get(Document, document_id)
        print(document.id)

Recent PRs like #24656 and #24135 improved session management by using explicit session scopes, but the error can still occur if ORM objects are passed between threads or tasks. For advanced debugging, add assertions or logging to detect ORM objects passed between threads, enable SQLAlchemy echo mode, or instrument the workflow engine to check for ORM objects in variable pools or node outputs [issue #26511].

Relevant code for pipeline indexing and session management is in api/services/rag_pipeline/, api/core/rag/index_processor/, and api/core/repositories/ [issue #26525].

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[Jekie1]

I can't upgrade right now, but I want to use a pipeline-style knowledge base. How can I upload files normally?

[dosubot[bot]]

You can work around this error by making sure your pipeline nodes and any custom code never pass ORM Document objects between steps, threads, or tasks. Instead, always pass just the document ID (e.g., document.id), and then re-query the Document inside each step using a new SQLAlchemy session. This prevents the object from becoming detached and avoids the session error [source].

For example, instead of:

# ❌ Bad: passing ORM object
def node_func(document: Document):
    print(document.id)  # document may be detached

Use:

# ✅ Good: passing only ID and re-querying
def node_func(document_id: int):
    with Session(engine) as session:
        document = session.get(Document, document_id)
        print(document.id)

Check your codebase (especially in api/services/rag_pipeline/, api/core/rag/index_processor/, and api/core/repositories/) for any place a Document object is passed between pipeline steps or background tasks, and refactor to use this pattern [source].

If you have custom pipeline nodes, apply the same logic: only pass IDs, and always re-query ORM objects inside a session. For extra safety, add logging or assertions to catch accidental ORM object passing between steps.

This workaround will let you upload files normally in pipeline-style knowledge bases until you can upgrade [source].

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}    

[Jekie1]

I am running a local deployment. How should I operate it?

[dosubot[bot]]

To operate your local Dify deployment and upload files using a pipeline-style knowledge base without hitting the SQLAlchemy session error, you need to make sure that pipeline nodes (and any custom code) never pass ORM Document objects between steps, threads, or tasks. Instead, always pass just the document ID (like document.id), and then re-query the Document inside each step using a new SQLAlchemy session. This avoids the "not bound to a Session" error because each step works with a fresh, attached ORM object.

For example, instead of:

# ❌ Bad: passing ORM object
def node_func(document: Document):
    print(document.id)  # document may be detached

Use:

# ✅ Good: passing only ID and re-querying
def node_func(document_id: int):
    with Session(engine) as session:
        document = session.get(Document, document_id)
        print(document.id)

After making these changes in your local codebase (look in api/services/rag_pipeline/, api/core/rag/index_processor/, and api/core/repositories/), restart your Dify API server and any pipeline worker/background task processes for the changes to take effect. Then, upload a file and check the logs—if you don't see the "Instance is not bound to a Session" error, the workaround is working as intended.

For local development, you can also enable SQLAlchemy echo mode or add logging to catch accidental ORM object passing between steps if you want to debug further. This pattern is confirmed as the correct workaround for local deployments until you can upgrade to a version with the official fix (source).

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}