[PR #327] docs: add embedding troubleshooting for stalled flows #321

New Issue

2026-06-06T22:10:12-04:00

yindo commented

2026-06-06 22:10:12 -04:00

📋 Pull Request Information

Original PR: https://github.com/vxcontrol/pentagi/pull/327
Author: @mason5052
Created: 6/1/2026
Status: 🔄 Open

Base: main ← Head: codex/issue-322-embedding-troubleshooting

📝 Commits (1)

2b625b3 docs: add embedding troubleshooting for stalled flows (#322)

📊 Changes

1 file changed (+29 additions, -0 deletions)

View changed files

📝 README.md (+29 -0)

📄 Description

Summary

Adds a troubleshooting subsection to the Embedding Configuration and Testing section of the README for the case where a flow starts but then waits indefinitely with no progress. Documentation only.

Problem

In #322 a user reported that a flow "just keeps waiting, nothing moving ahead." As noted on the issue, this symptom is frequently caused by a misconfigured or unreachable embedding provider rather than by the flow itself, and the suggested first step is to check docker logs pentagi and the embedding configuration guide. The README documents how to configure and test embeddings, but it does not connect the "flow hangs / never progresses" symptom to embedding provider settings, so users debug the flow instead of the provider.

Solution

A new ### Troubleshooting: Flow Stalls or Hangs Without Progress subsection placed at the end of the Embedding Configuration and Testing section. It gives a short, ordered diagnostic path that matches the maintainer guidance on the issue:

Check docker logs pentagi for embedding errors (auth, wrong model, timeout, TLS).
Run etester test -verbose to validate the embedding provider and database connection without starting a flow.
Verify the relevant .env settings, with cross-links to the existing Supported Embedding Providers and Why Consistent Embedding Providers Matter subsections.

Every environment variable referenced (EMBEDDING_PROVIDER, EMBEDDING_MODEL, EMBEDDING_URL, EMBEDDING_KEY, OPEN_AI_KEY, OPEN_AI_SERVER_URL, PROXY_URL, HTTP_CLIENT_TIMEOUT) already exists in both .env.example and backend/pkg/config/config.go. The LLM-provider fallback note mirrors the behavior already documented just above in the same section.

User Impact

Documentation only. No new environment variables, no provider default changes, and no code or test changes. Users who hit a stalled flow get a direct, ordered path to the likely embedding-provider cause instead of debugging the flow.

Test Plan

git diff --check reports no whitespace errors
Diff is a single file (README.md, 29 insertions); no code, schema, compose, or .env.example changes
Every referenced env var verified present in both .env.example and backend/pkg/config/config.go
No new environment variables and no provider defaults changed
Internal anchor links (#embedding-tester-utility-etester, #supported-embedding-providers, #why-consistent-embedding-providers-matter) resolve to existing headings

Refs #322

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/vxcontrol/pentagi/pull/327 **Author:** [@mason5052](https://github.com/mason5052) **Created:** 6/1/2026 **Status:** 🔄 Open **Base:** `main` ← **Head:** `codex/issue-322-embedding-troubleshooting` --- ### 📝 Commits (1) - [`2b625b3`](https://github.com/vxcontrol/pentagi/commit/2b625b31f1f8ef52542c8af7ba6337e44c94f755) docs: add embedding troubleshooting for stalled flows (#322) ### 📊 Changes **1 file changed** (+29 additions, -0 deletions) <details> <summary>View changed files</summary> 📝 `README.md` (+29 -0) </details> ### 📄 Description ## Summary Adds a troubleshooting subsection to the **Embedding Configuration and Testing** section of the README for the case where a flow starts but then waits indefinitely with no progress. Documentation only. ## Problem In #322 a user reported that a flow "just keeps waiting, nothing moving ahead." As noted on the issue, this symptom is frequently caused by a misconfigured or unreachable embedding provider rather than by the flow itself, and the suggested first step is to check `docker logs pentagi` and the embedding configuration guide. The README documents how to configure and test embeddings, but it does not connect the "flow hangs / never progresses" symptom to embedding provider settings, so users debug the flow instead of the provider. ## Solution A new `### Troubleshooting: Flow Stalls or Hangs Without Progress` subsection placed at the end of the Embedding Configuration and Testing section. It gives a short, ordered diagnostic path that matches the maintainer guidance on the issue: 1. Check `docker logs pentagi` for embedding errors (auth, wrong model, timeout, TLS). 2. Run `etester test -verbose` to validate the embedding provider and database connection without starting a flow. 3. Verify the relevant `.env` settings, with cross-links to the existing **Supported Embedding Providers** and **Why Consistent Embedding Providers Matter** subsections. Every environment variable referenced (`EMBEDDING_PROVIDER`, `EMBEDDING_MODEL`, `EMBEDDING_URL`, `EMBEDDING_KEY`, `OPEN_AI_KEY`, `OPEN_AI_SERVER_URL`, `PROXY_URL`, `HTTP_CLIENT_TIMEOUT`) already exists in both `.env.example` and `backend/pkg/config/config.go`. The LLM-provider fallback note mirrors the behavior already documented just above in the same section. ## User Impact Documentation only. No new environment variables, no provider default changes, and no code or test changes. Users who hit a stalled flow get a direct, ordered path to the likely embedding-provider cause instead of debugging the flow. ## Test Plan - [x] `git diff --check` reports no whitespace errors - [x] Diff is a single file (`README.md`, 29 insertions); no code, schema, compose, or `.env.example` changes - [x] Every referenced env var verified present in both `.env.example` and `backend/pkg/config/config.go` - [x] No new environment variables and no provider defaults changed - [x] Internal anchor links (`#embedding-tester-utility-etester`, `#supported-embedding-providers`, `#why-consistent-embedding-providers-matter`) resolve to existing headings Refs #322 --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

yindo added the pull-request label 2026-06-06 22:10:12 -04:00

yindo referenced this issue

2026-06-06 22:10:14 -04:00

[PR #331] docs: add native Google Vertex AI provider RFC #326

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: vxcontrol/pentagi#321