[DOCS]: Document Indexing Fails with 404 Errors During Embedding Process - #224

New Issue

Closed

opened 2026-02-16 05:19:29 -05:00 by yindo · 6 comments

yindo commented 2026-02-16 05:19:29 -05:00

Owner

Copy Link

Copy Source

Originally created by @jryanhaber on GitHub (Aug 12, 2025).

Type of Documentation Change

Other

Documentation Page URL or Path

No response

Current Content

Description:
When uploading documents to a Knowledge Base in Dify, the frontend
continuously polls for indexing status but receives 404 (NOT FOUND)
errors. The document indexing process fails to start properly due to
multiple configuration issues in the Docker environment.

Steps to Reproduce:

1. Upload a .txt file to a Knowledge Base in Dify
2. Open browser developer tools and monitor network requests
3. Observe continuous 404 errors for
   /console/api/datasets/{id}/batch/{batch_id}/indexing-status
4. Document appears to process but indexing never completes

Expected Behavior:
Document should be processed, embedded, and stored in the vector database
successfully with proper API responses for status polling.

Actual Behavior:

• Frontend shows continuous loading state for document processing
• Browser console shows repeated 404 errors for indexing status endpoint
• Document indexing batch records are never created in the database
• No indexing activity appears in API or worker container logs

Environment Details:

• Dify Version: 1.7.2 (Docker)
• Vector Database: Weaviate 1.19.0
• Docker Setup: Self-hosted via docker-compose
• Port Configuration: Custom port 9939 (mapped from nginx)
• Browser: Chrome with developer tools monitoring

Root Causes Identified:

1. Missing Vector Database Container
   - Weaviate was configured in .env (VECTOR_STORE=weaviate) but container
   wasn't running
   - Required manual start: docker compose --profile weaviate up weaviate
   -d
   - Fix: Started Weaviate container explicitly
2. Sandbox Python Environment Issues
   - Container logs showed: [WARN]python lib path /usr/lib/python3.10 is
   not available
   - Document processing requires Python for parsing/chunking
   - Fix: Created custom Dockerfile with proper Python installation and
   library paths
3. Locale Configuration Problems
   - Multiple containers showed: setlocale: LC_ALL: cannot change locale
   (en_US.UTF-8)
   - Affects text processing and encoding
   - Fix: Added LANG: en_US.UTF-8 and LC_ALL: en_US.UTF-8 to all API
   containers
4. Missing Embedding Provider Configuration
   - API container missing OPENAI_API_KEY environment variable
   - Without embedding provider, documents can't be vectorized
   - Status: Requires OpenAI API key configuration

Investigation Details:

Container Status Checked:
docker compose ps

Weaviate was missing from running containers

Log Analysis:
docker logs docker-sandbox-1 --tail 50

Showed Python path warnings during dependency updates

docker logs docker-api-1 --tail 100 | grep -E "(batch|index|dataset)"

No indexing activity found in API logs

Database Verification:
SELECT id, dataset_id, batch, indexing_status, created_at FROM documents
WHERE created_at > NOW() - INTERVAL '2 hours';

No recent document records found

Configuration Files Modified:

1. docker/docker-compose.yaml - Added locale env vars to
   api/worker/worker_beat
2. docker/sandbox/Dockerfile - Created custom image with Python setup
3. docker/.env - Added OPENAI_API_KEY= placeholder

Immediate Fixes Applied:

• ✅ Started Weaviate vector database container
• ✅ Fixed sandbox Python environment with custom Dockerfile
• ✅ Added locale configuration to prevent encoding issues
• ❌ Still needed: OpenAI API key configuration

Next Steps Required:

1. Add OpenAI API key to OPENAI_API_KEY= in /docker/.env
2. Restart API and worker containers: docker compose restart api worker
3. Test document upload to verify complete pipeline functionality

Technical Notes:

• Issue manifests as frontend 404 errors but root cause is backend
  indexing pipeline failure
• Multiple interconnected configuration problems prevented proper
  document processing
• Vector database availability is critical but not obvious from frontend
  error messages
• Sandbox container Python environment is essential for document parsing
  but errors are only visible in container logs

Suggested Changes

Clear setup instructions that show how to navigate these types of issues, informative console logs on errors or automated handling.

Clear docs indicating the known issues and what to do about them.

It does not make sense that I load my open ai in to the config but then the code fails if theres not also an api key in the .env, and the errors happen with almost zero clues as to the cause in the logs or error handling. Each critical error ( bad python, bad api key ) ideally would have a console log describing the issue somewhere.

Reason for Change

this is not about the docs, thats just the linked docs that failed to address these issues

Code of Conduct

• I agree to follow Dify's documentation contribution guidelines

Originally created by @jryanhaber on GitHub (Aug 12, 2025). ### Type of Documentation Change Other ### Documentation Page URL or Path _No response_ ### Current Content Description: When uploading documents to a Knowledge Base in Dify, the frontend continuously polls for indexing status but receives 404 (NOT FOUND) errors. The document indexing process fails to start properly due to multiple configuration issues in the Docker environment. Steps to Reproduce: 1. Upload a .txt file to a Knowledge Base in Dify 2. Open browser developer tools and monitor network requests 3. Observe continuous 404 errors for /console/api/datasets/{id}/batch/{batch_id}/indexing-status 4. Document appears to process but indexing never completes Expected Behavior: Document should be processed, embedded, and stored in the vector database successfully with proper API responses for status polling. Actual Behavior: - Frontend shows continuous loading state for document processing - Browser console shows repeated 404 errors for indexing status endpoint - Document indexing batch records are never created in the database - No indexing activity appears in API or worker container logs Environment Details: - Dify Version: 1.7.2 (Docker) - Vector Database: Weaviate 1.19.0 - Docker Setup: Self-hosted via docker-compose - Port Configuration: Custom port 9939 (mapped from nginx) - Browser: Chrome with developer tools monitoring Root Causes Identified: 1. Missing Vector Database Container - Weaviate was configured in .env (VECTOR_STORE=weaviate) but container wasn't running - Required manual start: docker compose --profile weaviate up weaviate -d - Fix: Started Weaviate container explicitly 2. Sandbox Python Environment Issues - Container logs showed: [WARN]python lib path /usr/lib/python3.10 is not available - Document processing requires Python for parsing/chunking - Fix: Created custom Dockerfile with proper Python installation and library paths 3. Locale Configuration Problems - Multiple containers showed: setlocale: LC_ALL: cannot change locale (en_US.UTF-8) - Affects text processing and encoding - Fix: Added LANG: en_US.UTF-8 and LC_ALL: en_US.UTF-8 to all API containers 4. Missing Embedding Provider Configuration - API container missing OPENAI_API_KEY environment variable - Without embedding provider, documents can't be vectorized - Status: Requires OpenAI API key configuration Investigation Details: Container Status Checked: docker compose ps # Weaviate was missing from running containers Log Analysis: docker logs docker-sandbox-1 --tail 50 # Showed Python path warnings during dependency updates docker logs docker-api-1 --tail 100 | grep -E "(batch|index|dataset)" # No indexing activity found in API logs Database Verification: SELECT id, dataset_id, batch, indexing_status, created_at FROM documents WHERE created_at > NOW() - INTERVAL '2 hours'; # No recent document records found Configuration Files Modified: 1. docker/docker-compose.yaml - Added locale env vars to api/worker/worker_beat 2. docker/sandbox/Dockerfile - Created custom image with Python setup 3. docker/.env - Added OPENAI_API_KEY= placeholder Immediate Fixes Applied: - ✅ Started Weaviate vector database container - ✅ Fixed sandbox Python environment with custom Dockerfile - ✅ Added locale configuration to prevent encoding issues - ❌ Still needed: OpenAI API key configuration Next Steps Required: 1. Add OpenAI API key to OPENAI_API_KEY= in /docker/.env 2. Restart API and worker containers: docker compose restart api worker 3. Test document upload to verify complete pipeline functionality Technical Notes: - Issue manifests as frontend 404 errors but root cause is backend indexing pipeline failure - Multiple interconnected configuration problems prevented proper document processing - Vector database availability is critical but not obvious from frontend error messages - Sandbox container Python environment is essential for document parsing but errors are only visible in container logs <img width="956" height="756" alt="Image" src="https://github.com/user-attachments/assets/81dee527-07e6-4126-ac1a-4898edcbd7ad" /> ### Suggested Changes Clear setup instructions that show how to navigate these types of issues, informative console logs on errors or automated handling. Clear docs indicating the known issues and what to do about them. It does not make sense that I load my open ai in to the config but then the code fails if theres not also an api key in the .env, and the errors happen with almost zero clues as to the cause in the logs or error handling. Each critical error ( bad python, bad api key ) ideally would have a console log describing the issue somewhere. ### Reason for Change this is not about the docs, thats just the linked docs that failed to address these issues ### Code of Conduct - [x] I agree to follow Dify's documentation [contribution guidelines](https://github.com/langgenius/dify/blob/0277a37fcad5ad86aeb239485c27fffd5cd90043/CONTRIBUTING.md)

yindo added the documentation label 2026-02-16 05:19:29 -05:00

yindo closed this issue 2026-02-16 05:19:29 -05:00

yindo commented 2026-02-16 05:19:29 -05:00

Author

Owner

Copy Link

Copy Source

@onestardao commented on GitHub (Aug 12, 2025):

Thanks for providing the detailed breakdown of the problem, environment, and suspected root causes — that really speeds up troubleshooting.

From the description, the key blockers seem to be:

Missing or misconfigured vector database container

    The logs and behavior indicate the API endpoint for embeddings is either unreachable or not responding, which often happens if the container isn’t running or is misconfigured.

    The VECTOR_STORE env var and vectorstore container config should be double-checked to ensure they match across services.

Runtime container setup issues

    The error during embedding hints that Python dependencies or locale settings inside the container might be missing.

    The missing python3.10-locale and incorrect locale configs would explain why some pipelines fail before actually storing vectors.

Embedding provider/API configuration

    If the API key or provider URL is wrong, the worker will fail silently until it hits a timeout.

    This would match the observed behavior of the process starting but never persisting embeddings.

Suggested next steps for the sprint:

Verify the vectorstore container is running and healthy (docker ps + check logs).

Align VECTOR_STORE env var values between the main app and worker services.

Install the missing locale dependencies inside the container or rebuild it with correct defaults.

Confirm that the embedding provider API key, endpoint URL, and model settings are valid and accessible from within the container (curl test).

Run the pipeline with a small test file to confirm the fix before scaling to larger documents.

If you’d like, I can draft a minimal Docker config patch that aligns the container setups and addresses the missing dependencies so we can test in the next sprint cycle.

@onestardao commented on GitHub (Aug 12, 2025): Thanks for providing the detailed breakdown of the problem, environment, and suspected root causes — that really speeds up troubleshooting. From the description, the key blockers seem to be: Missing or misconfigured vector database container The logs and behavior indicate the API endpoint for embeddings is either unreachable or not responding, which often happens if the container isn’t running or is misconfigured. The VECTOR_STORE env var and vectorstore container config should be double-checked to ensure they match across services. Runtime container setup issues The error during embedding hints that Python dependencies or locale settings inside the container might be missing. The missing python3.10-locale and incorrect locale configs would explain why some pipelines fail before actually storing vectors. Embedding provider/API configuration If the API key or provider URL is wrong, the worker will fail silently until it hits a timeout. This would match the observed behavior of the process starting but never persisting embeddings. Suggested next steps for the sprint: Verify the vectorstore container is running and healthy (docker ps + check logs). Align VECTOR_STORE env var values between the main app and worker services. Install the missing locale dependencies inside the container or rebuild it with correct defaults. Confirm that the embedding provider API key, endpoint URL, and model settings are valid and accessible from within the container (curl test). Run the pipeline with a small test file to confirm the fix before scaling to larger documents. If you’d like, I can draft a minimal Docker config patch that aligns the container setups and addresses the missing dependencies so we can test in the next sprint cycle.

yindo commented 2026-02-16 05:19:29 -05:00

Author

Owner

Copy Link

Copy Source

@crazywoola commented on GitHub (Aug 15, 2025):

@dosu validate this issue.

@crazywoola commented on GitHub (Aug 15, 2025): @dosu validate this issue.

yindo commented 2026-02-16 05:19:29 -05:00

Author

Owner

Copy Link

Copy Source

@dosubot[bot] commented on GitHub (Aug 15, 2025):

This issue is valid. The document indexing failures with 404 errors during embedding in Dify's Docker setup are caused by multiple configuration problems: missing or misconfigured vector database container (Weaviate), Python environment issues in the sandbox container, locale configuration problems, and missing OPENAI_API_KEY in the API container. These root causes and troubleshooting steps are accurate and align with Dify's architecture and deployment requirements. The lack of actionable error logs and setup guidance is a real gap—recent code changes have improved error handling and logging for indexing failures, but clearer setup instructions and more informative logs for critical environment issues are still needed to help users diagnose and resolve these problems efficiently.
Source 1 | Source 2

To reply, just mention @dosu.

---

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

@dosubot[bot] commented on GitHub (Aug 15, 2025): <!-- Answer --> This issue is valid. The document indexing failures with 404 errors during embedding in Dify's Docker setup are caused by multiple configuration problems: missing or misconfigured vector database container (Weaviate), Python environment issues in the sandbox container, locale configuration problems, and missing OPENAI_API_KEY in the API container. These root causes and troubleshooting steps are accurate and align with Dify's architecture and deployment requirements. The lack of actionable error logs and setup guidance is a real gap—recent code changes have improved error handling and logging for indexing failures, but clearer setup instructions and more informative logs for critical environment issues are still needed to help users diagnose and resolve these problems efficiently. [Source 1](https://github.com/langgenius/dify-docs/issues/397#issuecomment-3181977739) | [Source 2](https://github.com/langgenius/dify/pull/23046) <!-- Dosu Comment Footer --> *To reply, just mention [@dosu](https://go.dosu.dev/dosubot).* --- ^{How did I do? [Good](https://app.dosu.dev/response-feedback/f79d7823-9e81-4c10-9140-00b3cafc9fd2?feedback_type=great_response) | [Irrelevant](https://app.dosu.dev/response-feedback/f79d7823-9e81-4c10-9140-00b3cafc9fd2?feedback_type=irrelevant_answer) | [Incorrect](https://app.dosu.dev/response-feedback/f79d7823-9e81-4c10-9140-00b3cafc9fd2?feedback_type=incorrect_sources) | [Verbose](https://app.dosu.dev/response-feedback/f79d7823-9e81-4c10-9140-00b3cafc9fd2?feedback_type=too_verbose) | [Hallucination](https://app.dosu.dev/response-feedback/f79d7823-9e81-4c10-9140-00b3cafc9fd2?feedback_type=hallucination) | [Report 🐛](https://app.dosu.dev/response-feedback/f79d7823-9e81-4c10-9140-00b3cafc9fd2?feedback_type=bug_report) | [Other](https://app.dosu.dev/response-feedback/f79d7823-9e81-4c10-9140-00b3cafc9fd2?feedback_type=other)}&nbsp;&nbsp;[](https://go.dosu.dev/discord-bot)&nbsp;[](https://twitter.com/intent/tweet?text=%40dosu_ai%20helped%20me%20solve%20this%20issue!&url=https%3A//github.com/langgenius/dify-docs/issues/397)

yindo commented 2026-02-16 05:19:29 -05:00

Author

Owner

Copy Link

Copy Source

@jryanhaber commented on GitHub (Aug 15, 2025):

@crazywoola Thanks for the details on this.

I was really not clear on the docs what the options are for this. for other projects I have hand built vectorization systems and run them locally, and thats likely the direction I would take once I get past these issues if I go deeper here.

The biggest gap for me is that I was not able to get my agents familiar with your code even with the docs, so the process of trying to convert a sophisticated back end work flow into your system was super painful, even just getting to any measurable result was pretty challenging.

It might just be a learning curve and I can sense that this would have a lot of upside if I could get it running.

What you guys are building drag and drop, I have an already super robust agentic flow thats mostly hand coded plus langchain...

But in theory, If I could get your system working, I could take just the highest value elements out of it, wire into your system, and I think expose that as an api locally in my system, and then literally just call your functionality as though it is an operational back end.

Presumably I could then once working push it to production and let it operate at scale.

Is that a valid and actual use case here?

Would it be chaos?

Im not using docker at the moment. I run a front end and back end, back end in linode, front in vercel. Well, 3 front ends at the moment, soon to be 4.

Its rough trying to figure out if the tool your building will actually add value, it absolutely could, but will it...

For example, I literally just built a long term memory myself, extraction, vectorization, vector search, and injection into context in session.

And it looks like you have some drag and drop tools that would have handled that, cutting 20 hrs of work down to maybe 1 hr if i understood them well. but then, trying to figure out how to get your system into a production environment stably... thats what Im not clear about.

It could be that your intent is actually much more aligned with tinkering and testing and rapid iteration like zapier, but not really stable as a production deployment or reasonable.

Let me know?

You mentioned .env config, but is there a specific setup flow for what embedding systems I would use? Just one default?

I sure don't want to be tied to pinecone right, they overcharge like crazy.

If there was a setup step by step for vector memory, I just did not see it in the docs... seemed like you just mostly defined the key terms for some reason, let me know if I missed something.

Jonathan

@jryanhaber commented on GitHub (Aug 15, 2025): @crazywoola Thanks for the details on this. I was really not clear on the docs what the options are for this. for other projects I have hand built vectorization systems and run them locally, and thats likely the direction I would take once I get past these issues if I go deeper here. The biggest gap for me is that I was not able to get my agents familiar with your code even with the docs, so the process of trying to convert a sophisticated back end work flow into your system was super painful, even just getting to any measurable result was pretty challenging. It might just be a learning curve and I can sense that this would have a lot of upside if I could get it running. What you guys are building drag and drop, I have an already super robust agentic flow thats mostly hand coded plus langchain... But in theory, If I could get your system working, I could take just the highest value elements out of it, wire into your system, and _I think_ expose that as an api locally in my system, and then literally just call your functionality as though it is an operational back end. Presumably I could then once working push it to production and let it operate at scale. Is that a valid and actual use case here? Would it be chaos? Im not using docker at the moment. I run a front end and back end, back end in linode, front in vercel. Well, 3 front ends at the moment, soon to be 4. Its rough trying to figure out if the tool your building will actually add value, it absolutely could, but will it... For example, I literally just built a long term memory myself, extraction, vectorization, vector search, and injection into context in session. And it looks like you have some drag and drop tools that would have handled that, cutting 20 hrs of work down to maybe 1 hr if i understood them well. but then, trying to figure out how to get your system into a production environment stably... thats what Im not clear about. It could be that your intent is actually much more aligned with tinkering and testing and rapid iteration like zapier, but not really stable as a production deployment or reasonable. Let me know? You mentioned .env config, but is there a specific setup flow for what embedding systems I would use? Just one default? I sure don't want to be tied to pinecone right, they overcharge like crazy. If there was a setup step by step for vector memory, I just did not see it in the docs... seemed like you just mostly defined the key terms for some reason, let me know if I missed something. Jonathan

yindo commented 2026-02-16 05:19:29 -05:00

Author

Owner

Copy Link

Copy Source

@crazywoola commented on GitHub (Aug 18, 2025):

The biggest gap for me is that I was not able to get my agents familiar with your code even with the docs, so the process of trying to convert a sophisticated back end work flow into your system was super painful, even just getting to any measurable result was pretty challenging.

Well, we are trying to let the coding agents to understand our code base, but unfortunately, it still needs some time. Even for me, I can not guarantee I under 100% of our code bases, because it's rather big.

And it looks like you have some drag and drop tools that would have handled that, cutting 20 hrs of work down to maybe 1 hr if i understood them well. but then, trying to figure out how to get your system into a production environment stably... thats what Im not clear about.

If it can cut 20hrs of work down to maybe 1hr in a single team, then it will save lot's of man hours. I think it can be called as "real cases in the production". We do not recommend deploy the code through the source code, our enterprise version provide out-of-box solution, a helm chart. Which can scale the services at ease. Our saas platform has almost 1m users already which should be a solid proof of "Production".

It could be that your intent is actually much more aligned with tinkering and testing and rapid iteration like zapier, but not really stable as a production deployment or reasonable.

Actually, our slogan is "Dify offers everything you need — agentic workflows, RAG pipelines, integrations, and observability — all in one place, putting AI power into your hands.", you can find existing customers listed in our website. https://dify.ai

@crazywoola commented on GitHub (Aug 18, 2025): > The biggest gap for me is that I was not able to get my agents familiar with your code even with the docs, so the process of trying to convert a sophisticated back end work flow into your system was super painful, even just getting to any measurable result was pretty challenging. Well, we are trying to let the coding agents to understand our code base, but unfortunately, it still needs some time. Even for me, I can not guarantee I under 100% of our code bases, because it's rather big. > And it looks like you have some drag and drop tools that would have handled that, cutting 20 hrs of work down to maybe 1 hr if i understood them well. but then, trying to figure out how to get your system into a production environment stably... thats what Im not clear about. If it can cut 20hrs of work down to maybe 1hr in a single team, then it will save lot's of man hours. I think it can be called as "real cases in the production". We do not recommend deploy the code through the source code, our enterprise version provide out-of-box solution, a helm chart. Which can scale the services at ease. Our saas platform has almost 1m users already which should be a solid proof of "Production". > It could be that your intent is actually much more aligned with tinkering and testing and rapid iteration like zapier, but not really stable as a production deployment or reasonable. Actually, our slogan is "Dify offers everything you need — agentic workflows, RAG pipelines, integrations, and observability — all in one place, putting AI power into your hands.", you can find existing customers listed in our website. https://dify.ai

yindo commented 2026-02-16 05:19:29 -05:00

Author

Owner

Copy Link

Copy Source

@dosubot[bot] commented on GitHub (Aug 29, 2025):

Hi, @jryanhaber. I'm Dosu, and I'm helping the dify-docs team manage their backlog and am marking this issue as stale.

Issue Summary:

• You reported document indexing failures in Dify 1.7.2 Docker setup due to Weaviate container not running, missing Python environment, and locale misconfigurations.
• These issues caused continuous 404 errors during frontend polling.
• A detailed troubleshooting guide was provided focusing on container health, environment variables, and embedding API setup.
• Improvements in error handling were noted, but setup documentation gaps remain.
• You expressed concerns about system complexity and questioned its suitability for stable production use, with responses highlighting Dify’s production readiness and enterprise focus.

Next Steps:

• Please let me know if this issue is still relevant to the latest version of the dify-docs repository by commenting here to keep the discussion open.
• If I don’t hear back within 5 days, I will automatically close this issue.

Thank you for your understanding and contribution!

@dosubot[bot] commented on GitHub (Aug 29, 2025): Hi, @jryanhaber. I'm [Dosu](https://dosu.dev), and I'm helping the dify-docs team manage their backlog and am marking this issue as stale. **Issue Summary:** - You reported document indexing failures in Dify 1.7.2 Docker setup due to Weaviate container not running, missing Python environment, and locale misconfigurations. - These issues caused continuous 404 errors during frontend polling. - A detailed troubleshooting guide was provided focusing on container health, environment variables, and embedding API setup. - Improvements in error handling were noted, but setup documentation gaps remain. - You expressed concerns about system complexity and questioned its suitability for stable production use, with responses highlighting Dify’s production readiness and enterprise focus. **Next Steps:** - Please let me know if this issue is still relevant to the latest version of the dify-docs repository by commenting here to keep the discussion open. - If I don’t hear back within 5 days, I will automatically close this issue. Thank you for your understanding and contribution!

Sign in to join this conversation.

No Branch/Tag Specified

Branches Tags

main

release/1.15.0

release/1.16.0-rc1

release/1.16.0

fix/workflow-version-403

docs/app-runner

docs/snippets

backup-main-2026-06-25

release/1.14.2

release/1.14.1

release/1.14.0

docs/pdf-download

feat/evaluation-snippet

add/new-agent

add/llm-support-tool

add/end-user-oauth

auto-translate-works

update/clarify-app-types

revamp

refactor/knowledge

multimodal-embedding

refactor/variable

auto-translate-core

auto-translate

v1.14.2

v1.14.1

v1.14.0

v1.13.0

v1.12.1

v1.12.0

v1.11.4

v1.11.3

v1.11.2

v1.11.1

v1.11.0

Labels

Clear labels

bug

documentation

documentation

enhancement

pull-request

Mirrored from GitHub Pull Request

question

stale

No Label documentation

Milestone

No items

No Milestone

Projects

Clear projects

No project

Assignees

Clear assignees

yindo

No Assignees

1 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: langgenius/dify-docs#224