vxcontrol/pentagi · critical

failed to load flows: %w

Error message

failed to load flows: %w

What it means

LoadFlows reloads all flows from the database at startup and rebuilds in-memory flow workers. This error wraps a failure of fc.db.GetFlows(ctx), i.e., the initial DB query listing flows failed. Since LoadFlows typically runs during server bootstrap, this error usually means the application cannot restore its flow state.

Source

Thrown at backend/pkg/controller/flows.go:115

		flows:  make(map[int64]FlowWorker),
		docker: docker,
		provs:  provs,
		subs:   subs,
		alc:    NewAgentLogController(db),
		mlc:    NewMsgLogController(db),
		aslc:   NewAssistantLogController(db),
		slc:    NewSearchLogController(db),
		tlc:    NewTermLogController(db),
		vslc:   NewVectorStoreLogController(db),
		tclc:   NewToolCallLogController(db),
		sc:     NewScreenshotController(db),
	}
}

func (fc *flowController) LoadFlows(ctx context.Context) error {
	flows, err := fc.db.GetFlows(ctx)
	if err != nil {
		return fmt.Errorf("failed to load flows: %w", err)
	}

	for _, flow := range flows {
		fw, err := LoadFlowWorker(ctx, flow, flowWorkerCtx{
			db:     fc.db,
			cfg:    fc.cfg,
			docker: fc.docker,
			provs:  fc.provs,
			subs:   fc.subs,
			flowProviderControllers: flowProviderControllers{
				mlc:  fc.mlc,
				aslc: fc.aslc,
				alc:  fc.alc,
				slc:  fc.slc,
				tlc:  fc.tlc,
				vslc: fc.vslc,
				tclc: fc.tclc,
				sc:   fc.sc,

View on GitHub (pinned to ea665308ba)

Solutions

1. Verify PostgreSQL is reachable and credentials in env config are correct.
2. Run backend migrations (goose) so the flows table exists.
3. Add startup retry/backoff so DB readiness races don't abort boot.
4. Check the wrapped cause in logs for the precise driver error.

Example fix

// before
if err := fc.LoadFlows(ctx); err != nil {
	return fmt.Errorf("load flows: %w", err)
}
// after
err := retry.Do(func() error { return fc.LoadFlows(ctx) }, retry.Attempts(5), retry.Delay(time.Second))
if err != nil {
	return fmt.Errorf("load flows after retries: %w", err)
}

// before boot
if err := db.PingContext(ctx); err != nil {
	log.Fatal("database unreachable: ", err)
}

func isLoadFlowsError(err error) bool {
	return err != nil && strings.Contains(err.Error(), "failed to load flows")
}

if err := fc.LoadFlows(ctx); err != nil {
	// retry with backoff — DB may not be ready at startup
	return retry.Do(func() error { return fc.LoadFlows(ctx) },
		retry.Attempts(5), retry.Delay(2*time.Second))
}

When it happens

Trigger: Calling LoadFlows when the database is unreachable, credentials are wrong, the flows table is missing (migrations not run), or the query times out.

Common situations: App started before PostgreSQL is ready (container orchestration race); wrong DB_* env vars; failed/pending goose migrations; network partition to the DB.

Related errors

• failed to finish flow %d: %w
• token not found in database
• failed to create flow in DB: %w
• failed to get user %d: %w
• flow %d has status %s: loading aborted: %w

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