What causes "knowledge: list user docs: %w" in vxcontrol/pentagi?

Verify PostgreSQL is reachable and healthy (pg_isready, docker compose ps for the db service).

knowledge: list user docs: %w

Error message

knowledge: list user docs: %w

What it means

ListUserDocuments lists knowledge documents scoped to a user. When no filter narrows the result set, it runs the SQLC query ListUserKnowledgeDocuments against the pgvector-backed tables; if that query fails (DB down, bad SQL, context canceled), the error is wrapped with the 'knowledge: list user docs' prefix and returned.

Source

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

	var docs []*model.KnowledgeDocument

	if filter != nil && filter.FlowID != nil {
		// Flow-scoped listing; user_id check applied in Go for safety.
		rows, err := ks.db.ListFlowKnowledgeDocuments(ctx, nsOf(strconv.FormatInt(*filter.FlowID, 10)))
		if err != nil {
			return nil, fmt.Errorf("knowledge: list by flow (user): %w", err)
		}
		for _, r := range rows {
			meta := parseMeta(nullStr(r.Cmetadata))
			if strconv.FormatInt(meta.UserID, 10) != userIDStr {
				continue
			}
			docs = append(docs, rowToModel(r.ID, r.Document, nullStr(r.Cmetadata), withContent))
		}
	} else {
		rows, err := ks.db.ListUserKnowledgeDocuments(ctx, nsOf(userIDStr))
		if err != nil {
			return nil, fmt.Errorf("knowledge: list user docs: %w", err)
		}
		for _, r := range rows {
			docs = append(docs, rowToModel(r.ID, r.Document, nullStr(r.Cmetadata), withContent))
		}
	}

	return applyGoFilters(docs, filter), nil
}

// ---- GetDocument (admin) ----------------------------------------------------

func (ks *knowledgeStore) GetDocument(ctx context.Context, id string) (*model.KnowledgeDocument, error) {
	row, err := ks.db.GetKnowledgeDocument(ctx, id)
	if err != nil {
		return nil, fmt.Errorf("knowledge: get document %s: %w", id, err)
	}
	return rowToModel(row.ID, row.Document, nullStr(row.Cmetadata), true), nil
}

View on GitHub (pinned to ea665308ba)

Solutions

Verify PostgreSQL is reachable and healthy (pg_isready, docker compose ps for the db service).
Check server logs for the underlying wrapped error; it names the true cause (connection refused, relation does not exist, context canceled).
Run backend/migrations (goose) to ensure knowledge/pgvector tables and the vector extension exist.
Retry the request; transient connection-pool exhaustion resolves after load drops.

Example fix

// before
rows, err := ks.db.ListUserKnowledgeDocuments(ctx, nsOf(userIDStr)) // fails when DB unreachable
// after
if err := ks.db.Ping(ctx); err != nil {
    return nil, fmt.Errorf("knowledge: db unavailable: %w", err)
}
rows, err := ks.db.ListUserKnowledgeDocuments(ctx, nsOf(userIDStr))

Defensive patterns

Strategy: try-catch

Validate before calling

if err := dbConn.PingContext(ctx); err != nil {
    return nil, fmt.Errorf("database unavailable: %w", err)
}
if ctx.Err() != nil {
    return nil, ctx.Err()
}

Type guard

func isDBUnavailable(err error) bool {
    var opErr *net.OpError
    return errors.As(err, &opErr) || errors.Is(err, context.Canceled) || errors.Is(err, context.DeadlineExceeded)
}

Try / catch

docs, err := store.ListUserDocuments(ctx, userID, filter, true)
if err != nil {
    if isDBUnavailable(err) {
        return fmt.Errorf("knowledge temporarily unavailable: %w", err)
    }
    return err
}

Prevention

Run goose migrations at deploy time so knowledge tables always exist.
Monitor DB connection-pool saturation and set sane pool limits.
Always pass a request-scoped context with a reasonable timeout.
Alert on database connectivity so users see a health banner, not raw errors.

When it happens

Trigger: Calling ListUserDocuments with no metadata filter while the PostgreSQL connection is unavailable, the query times out, or ctx is canceled mid-query.

Common situations: Database restarted or connection pool exhausted; pgvector extension missing after a fresh deploy so the SQLC query errors; request context canceled by a disconnected GraphQL client.

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

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