vxcontrol/pentagi · error

knowledge: similarity search (admin): %w

Error message

knowledge: similarity search (admin): %w

What it means

The admin branch of doSearch runs SearchKnowledgeDocuments (no user filter) against pgvector. SQL failures — dimension mismatch, missing extension, connection errors — are wrapped as 'knowledge: similarity search (admin)'.

Source

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

			UserID:      nsOf(strconv.FormatInt(userID, 10)),
			MaxDistance: maxDist,
			Lim:         int32(limit), //nolint:gosec
		})
		if err != nil {
			return nil, fmt.Errorf("knowledge: similarity search (user %d): %w", userID, err)
		}
		rawRows = make([]searchRow, len(rows))
		for i, r := range rows {
			rawRows[i] = searchRow{r.ID, r.Document, r.Cmetadata, r.Score}
		}
	} else {
		rows, err := ks.db.SearchKnowledgeDocuments(ctx, database.SearchKnowledgeDocumentsParams{
			Embedding:   vecLiteral,
			MaxDistance: maxDist,
			Lim:         int32(limit), //nolint:gosec
		})
		if err != nil {
			return nil, fmt.Errorf("knowledge: similarity search (admin): %w", err)
		}
		rawRows = make([]searchRow, len(rows))
		for i, r := range rows {
			rawRows[i] = searchRow{r.ID, r.Document, r.Cmetadata, r.Score}
		}
	}

	results := make([]*model.KnowledgeDocumentWithScore, 0, len(rawRows))
	for _, r := range rawRows {
		doc := rowToModel(r.ID, r.Document, nullStr(r.Cmetadata), true)
		if !passesSearchFilter(doc, filter) {
			continue
		}
		results = append(results, &model.KnowledgeDocumentWithScore{
			Score:    r.Score,
			Document: doc,
		})
	}

View on GitHub (pinned to ea665308ba)

Solutions

1. Match the embedding model to the column dimension, or run a migration to alter the vector column and re-embed existing documents.
2. Ensure CREATE EXTENSION vector and knowledge tables exist (goose migrations) on fresh databases.
3. Check PostgreSQL connectivity and logs for the underlying error detail.
4. Verify maxDist/limit parameters are sane before the call.

Example fix

// before
vecLiteral := formatVector(vecs[0]) // dimension from current model
// after
if want, got := ks.vectorDim, len(vecs[0]); want != 0 && got != want {
    return nil, fmt.Errorf("knowledge: embedding dim %d != column dim %d", got, want)
}
vecLiteral := formatVector(vecs[0])

if strings.TrimSpace(query) == "" {
    return errors.New("query must not be empty")
}
if limit <= 0 {
    limit = defaultSearchLimit
}

func isDimensionMismatch(err error) bool {
    return strings.Contains(err.Error(), "different dimensions")
}

docs, err := store.SearchDocuments(ctx, query, filter, limit)
if err != nil {
    if isDimensionMismatch(err) {
        return fmt.Errorf("embedding model changed; re-index required: %w", err)
    }
    return err
}

When it happens

Trigger: Calling SearchDocuments when the embedding literal's dimension differs from the table's vector column, pgvector is not installed, or the database is unavailable.

Common situations: Changing the embedding provider/model after documents were stored (old 1536-dim vs new 768-dim vectors); clean deployment without migrations; DB outage.

Related errors

• knowledge: similarity search (user %d): %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/3217cb98d6d891b0. Report an issue: GitHub.