vxcontrol/pentagi · error

knowledge: list by flow: %w

Error message

knowledge: list by flow: %w

What it means

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.

Source

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

	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)))
		if err != nil {
			return nil, fmt.Errorf("knowledge: list by flow: %w", err)
		}
		for _, r := range rows {
			docs = append(docs, rowToModel(r.ID, r.Document, nullStr(r.Cmetadata), withContent))
		}
	} else {
		rows, err := ks.db.ListAllKnowledgeDocuments(ctx)
		if err != nil {
			return nil, fmt.Errorf("knowledge: list all: %w", err)
		}
		for _, r := range rows {
			docs = append(docs, rowToModel(r.ID, r.Document, nullStr(r.Cmetadata), withContent))
		}
	}

	return applyGoFilters(docs, filter), nil
}

// ---- ListUserDocuments (user-scoped) ----------------------------------------

View on GitHub (pinned to ea665308ba)

Solutions

1. Unwrap and inspect the driver error; check PostgreSQL logs for the failing query.
2. Verify DB connectivity and pool health (pg_isready, pool metrics).
3. Confirm the pgvector extension is installed and healthy in the database.
4. Add a query timeout / LIMIT or paginate results if the flow has a huge document count.
5. Retry transient connection errors with backoff.

Example fix

// before
rows, err := ks.db.ListFlowKnowledgeDocuments(ctx, ns)
if err != nil {
    return nil, fmt.Errorf("knowledge: list by flow: %w", err)
}
// after
rows, err := ks.db.ListFlowKnowledgeDocuments(ctx, ns)
if err != nil {
    if pgErr := (&pgconn.PgError{}); errors.As(err, pgErr) && pgErr.Code == "57014" {
        return nil, ErrKnowledgeListTimeout // query_cancelled: suggest narrowing filter
    }
    return nil, fmt.Errorf("knowledge: list by flow: %w", err)
}

if filter == nil || filter.FlowID == nil || *filter.FlowID <= 0 {
    return fmt.Errorf("flow-scoped listing requires a valid FlowID")
}
if err := ctx.Err(); err != nil {
    return nil, err
}

func isTransientDBError(err error) bool {
    var pgErr *pgconn.PgError
    if errors.As(err, &pgErr) {
        switch pgErr.Code {
        case "57014", "08006", "57P01": // cancelled, connection_failure, admin shutdown
            return true
        }
    }
    return errors.Is(err, context.DeadlineExceeded) || errors.Is(err, pgx.ErrDeadlock)
}

docs, err := kStore.ListDocuments(ctx, filter, withContent)
if err != nil {
    if isTransientDBError(err) {
        docs, err = retryWithBackoff(3, func() ([]*model.KnowledgeDocument, error) {
            return kStore.ListDocuments(ctx, filter, withContent)
        })
    }
    if err != nil { return nil, fmt.Errorf("knowledge list: %w", err) }
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: Database query failed: Internal Server Error 500s wrapping SQL, Prisma, and connection failures — what to check first — this error's family across 16 libraries.

Related errors

• knowledge: list all: %w
• knowledge: list by flow (user): %w
• failed to create flow in DB: %w
• failed to delete assistant %d: %w
• failed to rename flow %d: %w

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