langgenius/dify
1
0
Fork 0
mirror of https://github.com/langgenius/dify.git synced 2026-07-21 12:05:30 -04:00
Code Issues 775 Packages Projects Releases 10 Wiki Activity

Knowledge base upload parsing error #20966

New Issue
Closed
opened 2026-02-21 20:10:02 -05:00 by yindo · 4 comments
yindo commented 2026-02-21 20:10:02 -05:00
Owner
Copy Link
Copy Source

Originally created by @htk949 on GitHub (Dec 11, 2025).

Self Checks

  • I have read the Contributing Guide and Language Policy.
  • This is only for bug report, if you would like to ask a question, please head to Discussions.
  • I have searched for existing issues search for existing issues, including closed ones.
  • I confirm that I am using English to submit this report, otherwise it will be closed.
  • 【中文用户 & Non English User】请使用英语提交，否则会被关闭 ：）
  • Please do not modify this template :) and fill in all the required fields.

Dify version

1.9.1

Cloud or Self Hosted

Self Hosted (Docker)

Steps to reproduce

The knowledge base built using pipline reports an error when parsing uploaded files: Instance<Document at 0x7d744e49ecf0>is not bound to a Session; attribute refresh operation cannot proceed (Background on this error at: https://sqlalche.me/e/20/bhk3 )

Image

✔️ Expected Behavior

Complete upload and parsing

❌ Actual Behavior

No response

Originally created by @htk949 on GitHub (Dec 11, 2025). ### Self Checks - [x] I have read the [Contributing Guide](https://github.com/langgenius/dify/blob/main/CONTRIBUTING.md) and [Language Policy](https://github.com/langgenius/dify/issues/1542). - [x] This is only for bug report, if you would like to ask a question, please head to [Discussions](https://github.com/langgenius/dify/discussions/categories/general). - [x] I have searched for existing issues [search for existing issues](https://github.com/langgenius/dify/issues), including closed ones. - [x] I confirm that I am using English to submit this report, otherwise it will be closed. - [x] 【中文用户 & Non English User】请使用英语提交，否则会被关闭 ：） - [x] Please do not modify this template :) and fill in all the required fields. ### Dify version 1.9.1 ### Cloud or Self Hosted Self Hosted (Docker) ### Steps to reproduce The knowledge base built using pipline reports an error when parsing uploaded files: Instance<Document at 0x7d744e49ecf0>is not bound to a Session; attribute refresh operation cannot proceed (Background on this error at: https://sqlalche.me/e/20/bhk3 ) <img width="2544" height="1064" alt="Image" src="https://github.com/user-attachments/assets/717d42ec-5e94-4587-9af1-9e89a423dbe1" /> ### ✔️ Expected Behavior Complete upload and parsing ### ❌ Actual Behavior _No response_
yindo added the 🐞 bug label 2026-02-21 20:10:02 -05:00
yindo closed this issue 2026-02-21 20:10:02 -05:00
yindo commented 2026-02-21 20:10:02 -05:00
Author
Owner
Copy Link
Copy Source

@dosubot[bot] commented on GitHub (Dec 11, 2025):

The error happens because SQLAlchemy ORM objects like Document become detached from their session after a commit or when the session is closed. If you access lazy-loaded attributes or relationships on a detached instance, you get the "Instance is not bound to a Session" error (details).

In Dify's knowledge base pipeline, Document objects are created and committed, then async tasks (like parsing and indexing) re-query them from the database to ensure they're session-bound before processing. If any code tries to use a Document instance after its session is closed, or passes it between threads/tasks without re-querying, this error will occur (see code pattern).

Best practice: Always re-query Document objects from the database (using db.session.get(...) or similar) before accessing any attributes that require a session, especially in async or multi-threaded contexts. Avoid passing ORM objects between threads or tasks without re-binding them to an active session.

If you have custom code or plugins that modify the upload/parsing flow, check that they follow this pattern. If the error only happens for certain file types (like PDFs or Chinese text), try uploading other formats to help isolate the issue.

If you need to debug further, try to reproduce the error with a minimal example and check where the Document instance is accessed after its session is closed. This will help pinpoint the problematic workflow.

To reply, just mention @dosu.

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

Chat with Dosu Open in Cursor Join Discord Share on X

@dosubot[bot] commented on GitHub (Dec 11, 2025): <!-- Answer --> The error happens because SQLAlchemy ORM objects like Document become detached from their session after a commit or when the session is closed. If you access lazy-loaded attributes or relationships on a detached instance, you get the "Instance<Document> is not bound to a Session" error ([details](https://sqlalche.me/e/20/bhk3)). In Dify's knowledge base pipeline, Document objects are created and committed, then async tasks (like parsing and indexing) re-query them from the database to ensure they're session-bound before processing. If any code tries to use a Document instance after its session is closed, or passes it between threads/tasks without re-querying, this error will occur ([see code pattern](https://github.com/langgenius/dify/blob/7344adf65e03687d87c1b2d886e7621933eb79fc/api/core/indexing_runner.py#L27-L810)). **Best practice:** Always re-query Document objects from the database (using `db.session.get(...)` or similar) before accessing any attributes that require a session, especially in async or multi-threaded contexts. Avoid passing ORM objects between threads or tasks without re-binding them to an active session. If you have custom code or plugins that modify the upload/parsing flow, check that they follow this pattern. If the error only happens for certain file types (like PDFs or Chinese text), try uploading other formats to help isolate the issue. If you need to debug further, try to reproduce the error with a minimal example and check where the Document instance is accessed after its session is closed. This will help pinpoint the problematic workflow. <!-- Dosu Comment Footer --> *To reply, just mention [@dosu](https://go.dosu.dev/dosubot).* --- <sup>How did I do? [Good](https://app.dosu.dev/response-feedback/08d1b9bd-feef-4579-b9cc-57ef442116f4?feedback_type=great_response) | [Irrelevant](https://app.dosu.dev/response-feedback/08d1b9bd-feef-4579-b9cc-57ef442116f4?feedback_type=irrelevant_answer) | [Incorrect](https://app.dosu.dev/response-feedback/08d1b9bd-feef-4579-b9cc-57ef442116f4?feedback_type=incorrect_sources) | [Verbose](https://app.dosu.dev/response-feedback/08d1b9bd-feef-4579-b9cc-57ef442116f4?feedback_type=too_verbose) | [Hallucination](https://app.dosu.dev/response-feedback/08d1b9bd-feef-4579-b9cc-57ef442116f4?feedback_type=hallucination) | [Report 🐛](https://app.dosu.dev/response-feedback/08d1b9bd-feef-4579-b9cc-57ef442116f4?feedback_type=bug_report) | [Other](https://app.dosu.dev/response-feedback/08d1b9bd-feef-4579-b9cc-57ef442116f4?feedback_type=other)</sup> [![Chat with Dosu](https://dosu.dev/dosu-chat-badge.svg)](https://app.dosu.dev/6088a4f4-073a-43f3-b3d4-4f06fb0c05a0/ask?utm_source=github)&nbsp;[![Open in Cursor](https://dosu.dev/dosu-in-cursor.svg)](https://cursor.com/link/prompt?text=The%20error%20happens%20because%20SQLAlchemy%20ORM%20objects%20like%20Document%20become%20detached%20from%20their%20session%20after%20a%20commit%20or%20when%20the%20session%20is%20closed.%20If%20you%20access%20lazy-loaded%20attributes%20or%20relationships%20on%20a%20detached%20instance%2C%20you%20get%20the%20%22Instance%3CDocument%3E%20is%20not%20bound%20to%20a%20Session%22%20error%20%28%5Bdetails%5D%28https%3A//sqlalche.me/e/20/bhk3%29%29.%0A%0AIn%20Dify%27s%20knowledge%20base%20pipeline%2C%20Document%20objects%20are%20created%20and%20committed%2C%20then%20async%20tasks%20%28like%20parsing%20and%20indexing%29%20re-query%20them%20from%20the%20database%20to%20ensure%20they%27re%20session-bound%20before%20processing.%20If%20any%20code%20tries%20to%20use%20a%20Document%20instance%20after%20its%20session%20is%20closed%2C%20or%20passes%20it%20between%20threads/tasks%20without%20re-querying%2C%20this%20error%20will%20occur%20%28%5Bsee%20code%20pattern%5D%28https%3A//github.com/langgenius/dify/blob/7344adf65e03687d87c1b2d886e7621933eb79fc/api/core/indexing_runner.py%23L27-L810%29%29.%0A%0A%2A%2ABest%20practice%3A%2A%2A%20Always%20re-query%20Document%20objects%20from%20the%20database%20%28using%20%60db.session.get%28...%29%60%20or%20similar%29%20before%20accessing%20any%20attributes%20that%20require%20a%20session%2C%20especially%20in%20async%20or%20multi-threaded%20contexts.%20Avoid%20passing%20ORM%20objects%20between%20threads%20or%20tasks%20without%20re-binding%20them%20to%20an%20active%20session.%0A%0AIf%20you%20have%20custom%20code%20or%20plugins%20that%20modify%20the%20upload/parsing%20flow%2C%20check%20that%20they%20follow%20this%20pattern.%20If%20the%20error%20only%20happens%20for%20certain%20file%20types%20%28like%20PDFs%20or%20Chinese%20text%29%2C%20try%20uploading%20other%20formats%20to%20help%20isolate%20the%20issue.%0A%0AIf%20you%20need%20to%20debug%20further%2C%20try%20to%20reproduce%20the%20error%20with%20a%20minimal%20example%20and%20check%20where%20the%20Document%20instance%20is%20accessed%20after%20its%20session%20is%20closed.%20This%20will%20help%20pinpoint%20the%20problematic%20workflow.)&nbsp;[![Join Discord](https://img.shields.io/badge/join-5865F2?logo=discord&logoColor=white&label=)](https://go.dosu.dev/discord-bot)&nbsp;[![Share on X](https://img.shields.io/badge/X-share-black)](https://twitter.com/intent/tweet?text=%40dosu_ai%20helped%20me%20solve%20this%20issue!&url=https%3A//github.com/langgenius/dify/issues/29487)
yindo commented 2026-02-21 20:10:02 -05:00
Author
Owner
Copy Link
Copy Source

@htk949 commented on GitHub (Dec 11, 2025):

@dosu
My knowledge base pipline execution logic is to first parse the PDF through Mineru, then divide it into parent-child blocks and vectorize it. There was no problem during testing, but when I uploaded it after publishing, it reported this error.

Image
@htk949 commented on GitHub (Dec 11, 2025): @dosu My knowledge base pipline execution logic is to first parse the PDF through Mineru, then divide it into parent-child blocks and vectorize it. There was no problem during testing, but when I uploaded it after publishing, it reported this error. <img width="2107" height="427" alt="Image" src="https://github.com/user-attachments/assets/071c3c8e-e95c-4a7c-98e0-f5ac6a9dd8c9" />
yindo commented 2026-02-21 20:10:02 -05:00
Author
Owner
Copy Link
Copy Source

@dosubot[bot] commented on GitHub (Dec 11, 2025):

This error happens because, after publishing, your pipeline runs across multiple threads or tasks, which exposes SQLAlchemy session detachment bugs that don't appear in single-session test runs. When a Document ORM object is passed between pipeline steps, threads, or tasks without re-querying it in a new session, it becomes detached, leading to the "not bound to a Session" error during embedding or indexing. This is a known issue in Dify 1.9.1 and earlier pipeline workflows discussion issue.

The official fix is in Dify 2.0.0 beta and later (feat/rag-2 branch, PR #26480), which enforces passing only IDs between pipeline steps and always re-querying ORM objects inside a session context. If you can't upgrade, the recommended workaround is:

  • Refactor your pipeline so that you never pass ORM Document objects between steps, threads, or tasks. Instead, pass only the document ID.
  • In each step, re-query the Document using a new session context, like this:
from sqlalchemy.orm import Session

def node_func(document_id):
    with Session(bind=db.engine, expire_on_commit=False) as session:
        document = session.get(Document, document_id)
        # ... process document ...

Check your code in these directories: api/services/rag_pipeline/, api/core/rag/index_processor/, and api/core/repositories/ for any places where ORM objects might be passed between steps, and update them to use this pattern discussion.

After making changes, restart your API server and any pipeline/background workers. To debug, enable SQLAlchemy echo logging or add assertions to catch ORM objects leaking between threads. If the error persists, review your Docker/Postgres connection pool and worker concurrency settings, as environmental factors can also contribute to session detachment in production issue.

Once fixed, uploading and parsing should complete without the session error.

To reply, just mention @dosu.

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

Chat with Dosu Open in Cursor Join Discord Share on X

@dosubot[bot] commented on GitHub (Dec 11, 2025): <!-- Answer --> This error happens because, after publishing, your pipeline runs across multiple threads or tasks, which exposes SQLAlchemy session detachment bugs that don't appear in single-session test runs. When a Document ORM object is passed between pipeline steps, threads, or tasks without re-querying it in a new session, it becomes detached, leading to the "not bound to a Session" error during embedding or indexing. This is a known issue in Dify 1.9.1 and earlier pipeline workflows [discussion](https://github.com/langgenius/dify/discussions/27538) [issue](https://github.com/langgenius/dify/issues/26511#issuecomment-3353544481). The official fix is in Dify 2.0.0 beta and later (feat/rag-2 branch, PR #26480), which enforces passing only IDs between pipeline steps and always re-querying ORM objects inside a session context. If you can't upgrade, the recommended workaround is: - Refactor your pipeline so that you never pass ORM Document objects between steps, threads, or tasks. Instead, pass only the document ID. - In each step, re-query the Document using a new session context, like this: ```python from sqlalchemy.orm import Session def node_func(document_id): with Session(bind=db.engine, expire_on_commit=False) as session: document = session.get(Document, document_id) # ... process document ... ``` Check your code in these directories: `api/services/rag_pipeline/`, `api/core/rag/index_processor/`, and `api/core/repositories/` for any places where ORM objects might be passed between steps, and update them to use this pattern [discussion](https://github.com/langgenius/dify/discussions/27538). After making changes, restart your API server and any pipeline/background workers. To debug, enable SQLAlchemy echo logging or add assertions to catch ORM objects leaking between threads. If the error persists, review your Docker/Postgres connection pool and worker concurrency settings, as environmental factors can also contribute to session detachment in production [issue](https://github.com/langgenius/dify/issues/26511#issuecomment-3353544481). Once fixed, uploading and parsing should complete without the session error. <!-- Dosu Comment Footer --> *To reply, just mention [@dosu](https://go.dosu.dev/dosubot).* --- <sup>How did I do? [Good](https://app.dosu.dev/response-feedback/9ee49c61-8586-43b6-aa0c-7fea550f6377?feedback_type=great_response) | [Irrelevant](https://app.dosu.dev/response-feedback/9ee49c61-8586-43b6-aa0c-7fea550f6377?feedback_type=irrelevant_answer) | [Incorrect](https://app.dosu.dev/response-feedback/9ee49c61-8586-43b6-aa0c-7fea550f6377?feedback_type=incorrect_sources) | [Verbose](https://app.dosu.dev/response-feedback/9ee49c61-8586-43b6-aa0c-7fea550f6377?feedback_type=too_verbose) | [Hallucination](https://app.dosu.dev/response-feedback/9ee49c61-8586-43b6-aa0c-7fea550f6377?feedback_type=hallucination) | [Report 🐛](https://app.dosu.dev/response-feedback/9ee49c61-8586-43b6-aa0c-7fea550f6377?feedback_type=bug_report) | [Other](https://app.dosu.dev/response-feedback/9ee49c61-8586-43b6-aa0c-7fea550f6377?feedback_type=other)</sup> [![Chat with Dosu](https://dosu.dev/dosu-chat-badge.svg)](https://app.dosu.dev/6088a4f4-073a-43f3-b3d4-4f06fb0c05a0/ask?utm_source=github)&nbsp;[![Open in Cursor](https://dosu.dev/dosu-in-cursor.svg)](https://cursor.com/link/prompt?text=This%20error%20happens%20because%2C%20after%20publishing%2C%20your%20pipeline%20runs%20across%20multiple%20threads%20or%20tasks%2C%20which%20exposes%20SQLAlchemy%20session%20detachment%20bugs%20that%20don%27t%20appear%20in%20single-session%20test%20runs.%20When%20a%20Document%20ORM%20object%20is%20passed%20between%20pipeline%20steps%2C%20threads%2C%20or%20tasks%20without%20re-querying%20it%20in%20a%20new%20session%2C%20it%20becomes%20detached%2C%20leading%20to%20the%20%22not%20bound%20to%20a%20Session%22%20error%20during%20embedding%20or%20indexing.%20This%20is%20a%20known%20issue%20in%20Dify%201.9.1%20and%20earlier%20pipeline%20workflows%C2%A0%5Bdiscussion%5D%28https%3A//github.com/langgenius/dify/discussions/27538%29%C2%A0%5Bissue%5D%28https%3A//github.com/langgenius/dify/issues/26511%23issuecomment-3353544481%29.%0A%0AThe%20official%20fix%20is%20in%20Dify%202.0.0%20beta%20and%20later%20%28feat/rag-2%20branch%2C%20PR%20%2326480%29%2C%20which%20enforces%20passing%20only%20IDs%20between%20pipeline%20steps%20and%20always%20re-querying%20ORM%20objects%20inside%20a%20session%20context.%20If%20you%20can%27t%20upgrade%2C%20the%20recommended%20workaround%20is%3A%0A%0A-%20Refactor%20your%20pipeline%20so%20that%20you%20never%20pass%20ORM%20Document%20objects%20between%20steps%2C%20threads%2C%20or%20tasks.%20Instead%2C%20pass%20only%20the%20document%20ID.%0A-%20In%20each%20step%2C%20re-query%20the%20Document%20using%20a%20new%20session%20context%2C%20like%20this%3A%0A%0A%60%60%60python%0Afrom%20sqlalchemy.orm%20import%20Session%0A%0Adef%20node_func%28document_id%29%3A%0A%20%20%20%20with%20Session%28bind%3Ddb.engine%2C%20expire_on_commit%3DFalse%29%20as%20session%3A%0A%20%20%20%20%20%20%20%20document%20%3D%20session.get%28Document%2C%20document_id%29%0A%20%20%20%20%20%20%20%20%23%20...%20process%20document%20...%0A%60%60%60%0A%0ACheck%20your%20code%20in%20these%20directories%3A%20%60api/services/rag_pipeline/%60%2C%20%60api/core/rag/index_processor/%60%2C%20and%20%60api/core/repositories/%60%20for%20any%20places%20where%20ORM%20objects%20might%20be%20passed%20between%20steps%2C%20and%20update%20them%20to%20use%20this%20pattern%C2%A0%5Bdiscussion%5D%28https%3A//github.com/langgenius/dify/discussions/27538%29.%0A%0AAfter%20making%20changes%2C%20restart%20your%20API%20server%20and%20any%20pipeline/background%20workers.%20To%20debug%2C%20enable%20SQLAlchemy%20echo%20logging%20or%20add%20assertions%20to%20catch%20ORM%20objects%20leaking%20between%20threads.%20If%20the%20error%20persists%2C%20review%20your%20Docker/Postgres%20connection%20pool%20and%20worker%20concurrency%20settings%2C%20as%20environmental%20factors%20can%20also%20contribute%20to%20session%20detachment%20in%20production%C2%A0%5Bissue%5D%28https%3A//github.com/langgenius/dify/issues/26511%23issuecomment-3353544481%29.%0A%0AOnce%20fixed%2C%20uploading%20and%20parsing%20should%20complete%20without%20the%20session%20error.)&nbsp;[![Join Discord](https://img.shields.io/badge/join-5865F2?logo=discord&logoColor=white&label=)](https://go.dosu.dev/discord-bot)&nbsp;[![Share on X](https://img.shields.io/badge/X-share-black)](https://twitter.com/intent/tweet?text=%40dosu_ai%20helped%20me%20solve%20this%20issue!&url=https%3A//github.com/langgenius/dify/issues/29487)
yindo commented 2026-02-21 20:10:03 -05:00
Author
Owner
Copy Link
Copy Source

@crazywoola commented on GitHub (Dec 11, 2025):

Duplicated, please search existing issues instead.

@crazywoola commented on GitHub (Dec 11, 2025): Duplicated, please search existing issues instead.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
Knowledge Pipeline
Proposal
WIP
cloud
dependencies
feat:webapp
good first issue
outdated
performance
pull-request
Mirrored from GitHub Pull Request
 python:uv
refactor
size:L
stale
status: accepting prs
status: blocked
status: in discussion
stt & tts
vulnerablity
web
wont-fix
🌊 feat:workflow
🌚 invalid
🐞 bug
👻 feat:rag
💪 enhancement
📚 documentation
🔨 feat:tools
🙋‍♂️ question
🙏 help wanted
🤔 cant-reproduce
🤖 feat:agent
No Label 🐞 bug
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
yindo
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: langgenius/dify#20966
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?