vxcontrol/pentagi · error

knowledge: embedding provider is not configured

Error message

knowledge: embedding provider is not configured

What it means

requireStore is a guard used by knowledgeStore methods: it fails when the internal pgvector-backed store was never constructed because no embedding provider was configured. Without an embedder there is no way to vectorize documents, so all knowledge-base operations are refused with this message. It indicates a configuration problem, not a runtime failure.

Source

Thrown at backend/pkg/database/knowledge/knowledge.go:239

			continue
		}
		if len(filter.AnswerTypes) > 0 && (doc.AnswerType == nil || !slices.Contains(filter.AnswerTypes, *doc.AnswerType)) {
			continue
		}
		if len(filter.CodeLangs) > 0 && (doc.CodeLang == nil || !slices.Contains(filter.CodeLangs, *doc.CodeLang)) {
			continue
		}
		if filter.Manual != nil && doc.Manual != *filter.Manual {
			continue
		}
		result = append(result, doc)
	}
	return result
}

func (ks *knowledgeStore) requireStore() error {
	if ks.store == nil {
		return fmt.Errorf("knowledge: embedding provider is not configured")
	}
	return nil
}

func (ks *knowledgeStore) requireEmbedder() error {
	if ks.embedder == nil || !ks.embedder.IsAvailable() {
		return fmt.Errorf("knowledge: embedding provider is not available")
	}
	return nil
}

// ---- ListDocuments (admin) --------------------------------------------------

func (ks *knowledgeStore) ListDocuments(ctx context.Context, filter *model.KnowledgeFilter, withContent bool) ([]*model.KnowledgeDocument, error) {
	var docs []*model.KnowledgeDocument

	if filter != nil && filter.FlowID != nil {
		rows, err := ks.db.ListFlowKnowledgeDocuments(ctx, nsOf(strconv.FormatInt(*filter.FlowID, 10)))

View on GitHub (pinned to ea665308ba)

Solutions

1. Configure an embedding provider: set the embedding API key/model env vars (see .env.example) and restart.
2. In the Settings UI, enable a provider that supports embeddings and select an embedding model.
3. If embeddings are intentionally unavailable, disable knowledge-base features instead of calling the store.
4. Guard feature code with a capability check (embedder availability) before invoking knowledge operations.

Example fix

// before
docs, err := kStore.Search(ctx, flowID, query, limit) // fails: not configured
// after
if err := kStore.CheckAvailability(); err != nil {
    return nil, fmt.Errorf("knowledge base disabled: %w", err) // degrade gracefully
}
docs, err := kStore.Search(ctx, flowID, query, limit)

// before using the knowledge base, check configuration
if err := kStore.CheckAvailability(); err != nil {
    // knowledge: embedding provider is not configured
    disableKnowledgeFeatures(err)
    return
}

func isEmbeddingNotConfigured(err error) bool {
    return err != nil && strings.Contains(err.Error(), "embedding provider is not configured")
}

docs, err := kStore.Search(ctx, flowID, query, limit)
if err != nil {
    if strings.Contains(err.Error(), "embedding provider is not configured") {
        return nil, ErrKnowledgeDisabled // surface as feature-disabled, not 500
    }
    return err
}

When it happens

Trigger: Any knowledge-store call (search, create, update, list-backed operations) when the app started without an embedding provider configured (no EMBEDDING_* / provider env vars, or the chosen provider has no embedding capability).

Common situations: Deploying with .env lacking embedding provider settings; enabling the knowledge-base feature while only configuring chat LLM providers; a provider that exposes chat but not embeddings (e.g. some Ollama setups).

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• knowledge: embedding provider is not available
• token validation disabled with default salt
• failed to switch provider: %w
• knowledge: embed query: %w
• knowledge: compute embedding: %w

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