vxcontrol/pentagi · error

failed to store guide: %w

Error message

failed to store guide: %w

What it means

The fast path of store_guide — when the anonymized guide fits within maxEmbeddingBytes — failed while adding the document to the pgvector store. Same failure class as the load-document error but on the direct AddDocuments branch.

Source

Thrown at backend/pkg/tools/guide.go:300

				logger.WithError(err).Error("failed to load document")
				return "", fmt.Errorf("failed to load document: %w", err)
			}
			for i := range docs {
				if docs[i].Metadata == nil {
					docs[i].Metadata = map[string]any{}
				}
				maps.Copy(docs[i].Metadata, metadata)
				docs[i].Metadata["part_size"] = len(docs[i].PageContent)
			}
			ids, err = g.store.AddDocuments(ctx, docs)
			eventMetadata["ids"] = ids
			if err != nil {
				observation.Event(append(opts,
					langfuse.WithEventStatus(err.Error()),
					langfuse.WithEventLevel(langfuse.ObservationLevelError),
				)...)
				logger.WithError(err).Error("failed to store guide")
				return "", fmt.Errorf("failed to store guide: %w", err)
			}
		} else {
			// Slow path: Guide field exceeds embedding limit.
			// Template: "Question:\n{question}\n\nGuide:\n{guide}"
			prefix := "Question:\n" + anonymizedQuestion + "\n\nGuide:\n"
			available := max(g.maxEmbeddingBytes-len(prefix), 0)
			embeddingText := prefix + truncateForEmbedding(anonymizedGuideOnly, available)

			id, err := storeDocumentWithEmbeddingLimit(ctx, g.db, g.embedder,
				embeddingText, anonymizedGuide, metadata)
			if err != nil {
				observation.Event(append(opts,
					langfuse.WithEventStatus(err.Error()),
					langfuse.WithEventLevel(langfuse.ObservationLevelError),
				)...)
				logger.WithError(err).Error("failed to store guide with embedding limit")
				return "", fmt.Errorf("failed to store guide: %w", err)
			}

View on GitHub (pinned to ea665308ba)

Solutions

1. Inspect the wrapped cause to separate embedder vs DB failure.
2. Fix embeddings credentials/quota or provider URL in config (.env / Settings UI).
3. Run migrations to ensure the pgvector schema exists.
4. Retry the store_guide call — transient API/rate-limit errors resolve on retry.
5. Check DB connectivity and pool exhaustion in PostgreSQL logs.

func canEmbed(ctx context.Context, e embeddings.Embedder, text string) error {
    _, err := e.EmbedDocuments(ctx, []string{text[:min(len(text), 64)]})
    return err
}

func embeddingsConfigured(store *pgvector.Store, e embeddings.Embedder) bool {
    return store != nil && e != nil
}

out, err := tool.Handle(ctx, "store_guide", args)
if err != nil && strings.Contains(err.Error(), "failed to store guide") {
    return withRetry(3, backoff.Exponential, func() error {
        _, err = tool.Handle(ctx, "store_guide", args)
        return err
    })
}

When it happens

Trigger: Embedder API failure (auth, quota, timeout) or pgvector insert failure when calling store_guide with a guide whose serialized form fits the embedding byte limit.

Common situations: Expired/invalid embeddings API key; embeddings provider rate-limited mid-flow; PostgreSQL down or pgvector table missing; context deadline exceeded on a slow embedder.

Related errors

• failed to load document: %w
• failed to create flow vector store log: %w
• failed to get flow vector store log: %w
• knowledge: list by flow: %w
• knowledge: list all: %w

AI-assisted analysis of vxcontrol/pentagi@ea665308ba (2026-09-01). Data as JSON: /api/errors/204525591b384eba. Report an issue: GitHub.