{"record":{"id":"f32c995510ec06f5","repo":"vxcontrol/pentagi","slug":"knowledge-list-by-flow-w","errorCode":null,"errorMessage":"knowledge: list by flow: %w","messagePattern":"knowledge: list by flow: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"backend/pkg/database/knowledge/knowledge.go","lineNumber":259,"sourceCode":"\treturn nil\n}\n\nfunc (ks *knowledgeStore) requireEmbedder() error {\n\tif ks.embedder == nil || !ks.embedder.IsAvailable() {\n\t\treturn fmt.Errorf(\"knowledge: embedding provider is not available\")\n\t}\n\treturn nil\n}\n\n// ---- ListDocuments (admin) --------------------------------------------------\n\nfunc (ks *knowledgeStore) ListDocuments(ctx context.Context, filter *model.KnowledgeFilter, withContent bool) ([]*model.KnowledgeDocument, error) {\n\tvar docs []*model.KnowledgeDocument\n\n\tif filter != nil && filter.FlowID != nil {\n\t\trows, err := ks.db.ListFlowKnowledgeDocuments(ctx, nsOf(strconv.FormatInt(*filter.FlowID, 10)))\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"knowledge: list by flow: %w\", err)\n\t\t}\n\t\tfor _, r := range rows {\n\t\t\tdocs = append(docs, rowToModel(r.ID, r.Document, nullStr(r.Cmetadata), withContent))\n\t\t}\n\t} else {\n\t\trows, err := ks.db.ListAllKnowledgeDocuments(ctx)\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"knowledge: list all: %w\", err)\n\t\t}\n\t\tfor _, r := range rows {\n\t\t\tdocs = append(docs, rowToModel(r.ID, r.Document, nullStr(r.Cmetadata), withContent))\n\t\t}\n\t}\n\n\treturn applyGoFilters(docs, filter), nil\n}\n\n// ---- ListUserDocuments (user-scoped) ----------------------------------------","sourceCodeStart":241,"sourceCodeEnd":277,"githubUrl":"https://github.com/vxcontrol/pentagi/blob/ea665308baaff015b226f308438a68d929d0f29b/backend/pkg/database/knowledge/knowledge.go#L241-L277","documentation":"ListDocuments wraps failures of the ListFlowKnowledgeDocuments SQLC query (used when the filter specifies a FlowID) as \"knowledge: list by flow: %w\". The underlying pgvector database query failed — connectivity, SQL error, or context cancellation — while listing knowledge documents scoped to one flow.","triggerScenarios":"Calling ListDocuments(ctx, filter with FlowID set, withContent) when PostgreSQL is down/unreachable, the namespace conversion fails to match rows, the query times out, or pgvector extension errors occur.","commonSituations":"DB connection pool exhaustion during heavy agent runs; pgvector extension version mismatch after an upgrade; network partition to the database; very large per-flow document sets causing slow queries and timeouts.","solutions":["Unwrap and inspect the driver error; check PostgreSQL logs for the failing query.","Verify DB connectivity and pool health (pg_isready, pool metrics).","Confirm the pgvector extension is installed and healthy in the database.","Add a query timeout / LIMIT or paginate results if the flow has a huge document count.","Retry transient connection errors with backoff."],"exampleFix":"// before\nrows, err := ks.db.ListFlowKnowledgeDocuments(ctx, ns)\nif err != nil {\n    return nil, fmt.Errorf(\"knowledge: list by flow: %w\", err)\n}\n// after\nrows, err := ks.db.ListFlowKnowledgeDocuments(ctx, ns)\nif err != nil {\n    if pgErr := (&pgconn.PgError{}); errors.As(err, pgErr) && pgErr.Code == \"57014\" {\n        return nil, ErrKnowledgeListTimeout // query_cancelled: suggest narrowing filter\n    }\n    return nil, fmt.Errorf(\"knowledge: list by flow: %w\", err)\n}","handlingStrategy":"retry","validationCode":"if filter == nil || filter.FlowID == nil || *filter.FlowID <= 0 {\n    return fmt.Errorf(\"flow-scoped listing requires a valid FlowID\")\n}\nif err := ctx.Err(); err != nil {\n    return nil, err\n}","typeGuard":"func isTransientDBError(err error) bool {\n    var pgErr *pgconn.PgError\n    if errors.As(err, &pgErr) {\n        switch pgErr.Code {\n        case \"57014\", \"08006\", \"57P01\": // cancelled, connection_failure, admin shutdown\n            return true\n        }\n    }\n    return errors.Is(err, context.DeadlineExceeded) || errors.Is(err, pgx.ErrDeadlock)\n}","tryCatchPattern":"docs, err := kStore.ListDocuments(ctx, filter, withContent)\nif err != nil {\n    if isTransientDBError(err) {\n        docs, err = retryWithBackoff(3, func() ([]*model.KnowledgeDocument, error) {\n            return kStore.ListDocuments(ctx, filter, withContent)\n        })\n    }\n    if err != nil { return nil, fmt.Errorf(\"knowledge list: %w\", err) }\n}","preventionTips":["Keep PostgreSQL and the pgvector extension versions aligned with app requirements.","Monitor DB pool utilization and connection errors.","Paginate or LIMIT flow-scoped listings for large document sets.","Set sensible statement timeouts and surface them as user-readable errors."],"tags":["go","database","postgres","pgvector","query-failed"],"backgroundTag":"database-query-failed","analyzedSha":"ea665308baaff015b226f308438a68d929d0f29b","analyzedAt":"2026-09-01T14:16:31.421Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}