{"record":{"id":"3217cb98d6d891b0","repo":"vxcontrol/pentagi","slug":"knowledge-similarity-search-admin-w","errorCode":null,"errorMessage":"knowledge: similarity search (admin): %w","messagePattern":"knowledge: similarity search \\(admin\\): %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"backend/pkg/database/knowledge/knowledge.go","lineNumber":411,"sourceCode":"\t\t\tUserID:      nsOf(strconv.FormatInt(userID, 10)),\n\t\t\tMaxDistance: maxDist,\n\t\t\tLim:         int32(limit), //nolint:gosec\n\t\t})\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"knowledge: similarity search (user %d): %w\", userID, err)\n\t\t}\n\t\trawRows = make([]searchRow, len(rows))\n\t\tfor i, r := range rows {\n\t\t\trawRows[i] = searchRow{r.ID, r.Document, r.Cmetadata, r.Score}\n\t\t}\n\t} else {\n\t\trows, err := ks.db.SearchKnowledgeDocuments(ctx, database.SearchKnowledgeDocumentsParams{\n\t\t\tEmbedding:   vecLiteral,\n\t\t\tMaxDistance: maxDist,\n\t\t\tLim:         int32(limit), //nolint:gosec\n\t\t})\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"knowledge: similarity search (admin): %w\", err)\n\t\t}\n\t\trawRows = make([]searchRow, len(rows))\n\t\tfor i, r := range rows {\n\t\t\trawRows[i] = searchRow{r.ID, r.Document, r.Cmetadata, r.Score}\n\t\t}\n\t}\n\n\tresults := make([]*model.KnowledgeDocumentWithScore, 0, len(rawRows))\n\tfor _, r := range rawRows {\n\t\tdoc := rowToModel(r.ID, r.Document, nullStr(r.Cmetadata), true)\n\t\tif !passesSearchFilter(doc, filter) {\n\t\t\tcontinue\n\t\t}\n\t\tresults = append(results, &model.KnowledgeDocumentWithScore{\n\t\t\tScore:    r.Score,\n\t\t\tDocument: doc,\n\t\t})\n\t}","sourceCodeStart":393,"sourceCodeEnd":429,"githubUrl":"https://github.com/vxcontrol/pentagi/blob/ea665308baaff015b226f308438a68d929d0f29b/backend/pkg/database/knowledge/knowledge.go#L393-L429","documentation":"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)'.","triggerScenarios":"Calling SearchDocuments when the embedding literal's dimension differs from the table's vector column, pgvector is not installed, or the database is unavailable.","commonSituations":"Changing the embedding provider/model after documents were stored (old 1536-dim vs new 768-dim vectors); clean deployment without migrations; DB outage.","solutions":["Match the embedding model to the column dimension, or run a migration to alter the vector column and re-embed existing documents.","Ensure CREATE EXTENSION vector and knowledge tables exist (goose migrations) on fresh databases.","Check PostgreSQL connectivity and logs for the underlying error detail.","Verify maxDist/limit parameters are sane before the call."],"exampleFix":"// before\nvecLiteral := formatVector(vecs[0]) // dimension from current model\n// after\nif want, got := ks.vectorDim, len(vecs[0]); want != 0 && got != want {\n    return nil, fmt.Errorf(\"knowledge: embedding dim %d != column dim %d\", got, want)\n}\nvecLiteral := formatVector(vecs[0])","handlingStrategy":"validation","validationCode":"if strings.TrimSpace(query) == \"\" {\n    return errors.New(\"query must not be empty\")\n}\nif limit <= 0 {\n    limit = defaultSearchLimit\n}","typeGuard":"func isDimensionMismatch(err error) bool {\n    return strings.Contains(err.Error(), \"different dimensions\")\n}","tryCatchPattern":"docs, err := store.SearchDocuments(ctx, query, filter, limit)\nif err != nil {\n    if isDimensionMismatch(err) {\n        return fmt.Errorf(\"embedding model changed; re-index required: %w\", err)\n    }\n    return err\n}","preventionTips":["Store the embedding model name/dimension in table metadata and verify before searching.","Verify CREATE EXTENSION vector exists in a startup check.","Re-index documents after any provider/model switch.","Gate model changes behind a documented migration path."],"tags":["database","pgvector","sql"],"backgroundTag":"vector-dimension-mismatch","analyzedSha":"ea665308baaff015b226f308438a68d929d0f29b","analyzedAt":"2026-09-01T14:16:31.421Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}