vxcontrol/pentagi · error

failed to load document: %w

Error message

failed to load document: %w

What it means

Failed to load the anonymized guide document into the pgvector store via langchaingo's documentloader/add-documents path. The embedder call or the underlying database insert during AddDocuments returned an error.

Source

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

			metadata["subtask_id"] = *g.subtaskID
		}

		var (
			docs []schema.Document
			ids  []string
			err  error
		)

		if len(anonymizedGuide) <= g.maxEmbeddingBytes || g.embedder == nil {
			// Fast path: document fits within the embedding limit.
			docs, err = documentloaders.NewText(strings.NewReader(anonymizedGuide)).Load(ctx)
			if err != nil {
				observation.Event(append(opts,
					langfuse.WithEventStatus(err.Error()),
					langfuse.WithEventLevel(langfuse.ObservationLevelError),
				)...)
				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)
			}

View on GitHub (pinned to ea665308ba)

Solutions

1. Read the wrapped error (%w): if it's an embeddings API error, fix the provider key/URL/quota.
2. If it's a database error, verify pgvector is installed and migrations ran (goose) in the backend DB.
3. Test embeddings connectivity (cmd/etester helper binary).
4. Check network/DNS from the Docker container to the embeddings endpoint.
5. Verify PostgreSQL connectivity and connection-pool limits.

// before calling store_guide, verify dependencies
if embedder == nil { return errors.New("embedder not configured") }
if err := db.PingContext(ctx); err != nil { return fmt.Errorf("db unreachable: %w", err) }

func storeReady(g *guide) bool { return g.store != nil && g.embedder != nil && g.db != nil }

out, err := tool.Handle(ctx, "store_guide", args)
if err != nil && strings.Contains(err.Error(), "failed to load document") {
    if retriable(err) { // network/timeout/quota classes
        time.Sleep(backoff)
        return retry()
    }
    return fmt.Errorf("guide storage failed permanently: %w", err)
}

When it happens

Trigger: Calling the store_guide tool when the embeddings provider is unreachable/misconfigured, the pgvector extension/table is missing, or the DB connection is down during AddDocuments.

Common situations: OPENAI/other embeddings API key invalid or quota exhausted; PostgreSQL without the pgvector extension or with an old schema; DB max connections exhausted; network egress blocked from the container to the embeddings API.

Related errors

• failed to store guide: %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/7292d151eee41114. Report an issue: GitHub.