vxcontrol/pentagi · error

knowledge: embed query: %w

Error message

knowledge: embed query: %w

What it means

doSearch computes a query embedding via the configured Embedder before running the pgvector similarity query. Any failure from embedder.EmbedDocuments (nil embedder, provider misconfigured, API/network failure) is wrapped as 'knowledge: embed query'.

Source

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

//     the Manual flag that cannot be expressed as static SQL predicates.
func (ks *knowledgeStore) doSearch(ctx context.Context, userID int64, query string, filter *model.KnowledgeFilter, limit int) ([]*model.KnowledgeDocumentWithScore, error) {
	if err := ks.requireEmbedder(); err != nil {
		return nil, err
	}
	if limit <= 0 {
		limit = defaultSearchLimit
	}

	// Truncate query to embedding size limit to avoid token limit errors.
	// The search quality is preserved since the most relevant context is at the start.
	if len(query) > ks.maxEmbeddingBytes {
		query = query[:ks.maxEmbeddingBytes]
	}

	// Compute query embedding.
	vecs, err := ks.embedder.EmbedDocuments(ctx, []string{query})
	if err != nil {
		return nil, fmt.Errorf("knowledge: embed query: %w", err)
	}
	if len(vecs) == 0 {
		return nil, fmt.Errorf("knowledge: embedder returned no vectors for query")
	}

	vecLiteral := formatVector(vecs[0])
	// maxDist is the cosine-distance upper bound (exclusive):
	// distance = 1 - similarity, so maxDist = 1 - threshold.
	maxDist := float64(1.0 - defaultSearchThreshold)

	type searchRow struct {
		ID        string
		Document  string
		Cmetadata sql.NullString
		Score     float64
	}

	var rawRows []searchRow

View on GitHub (pinned to ea665308ba)

Solutions

1. Check the wrapped cause: 'embedder is not configured' means set the embedding provider env vars and restart.
2. Validate the embedding provider API key and server URL; test with a direct curl to the embeddings endpoint.
3. Verify network/DNS from the backend container to the embedding provider (ollama hostname, proxy settings).
4. Retry with backoff if the cause is a transient 429/5xx from the provider.

Example fix

// before
vecs, err := ks.embedder.EmbedDocuments(ctx, []string{query})
// after
if ks.embedder == nil {
    return nil, fmt.Errorf("knowledge: embedding provider not configured")
}
vecs, err := ks.embedder.EmbedDocuments(ctx, []string{query})

if embedder == nil {
    return errors.New("embedding provider not configured; set embedding env vars")
}
if strings.TrimSpace(query) == "" {
    return errors.New("query must not be empty")
}

func isEmbedderConfigErr(err error) bool {
    return strings.Contains(err.Error(), "not configured")
}

results, err := store.SearchDocuments(ctx, query, filter, limit)
if err != nil {
    var retryable bool
    if errors.As(err, &httpRateLimitErr{}) {
        retryable = true
    }
    if retryable {
        // retry with exponential backoff
    }
    return err
}

When it happens

Trigger: SearchDocuments or SearchUserDocuments called when no embedding provider is configured (embedder nil), the provider API key is invalid/expired, or the embedding endpoint is unreachable/times out.

Common situations: Deployment without embedding env vars so the store was built with a nil embedder; OpenAI/Ollama endpoint down or wrong URL; rate limit or 401 from the embedding provider.

Related errors

• knowledge: compute embedding: %w
• knowledge: embedding provider is not configured
• failed to load document: %w
• token validation disabled with default salt
• Token.CreationDisabled

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