vxcontrol/pentagi · error

failed to load flow %d: %w

Error message

failed to load flow %d: %w

What it means

Wrap in the loadFlow closure of CreateAssistant when LoadFlowWorker cannot rebuild an in-memory FlowWorker from the persisted flow record. The DB status update succeeded but reconstructing the worker (rehydrating providers, functions, Docker refs) failed.

Source

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

		fc.flows[fw.GetFlowID()] = fw
		flowID = fw.GetFlowID()
		fw.SetStatus(ctx, database.FlowStatusWaiting)

		return nil
	}

	loadFlow := func() error {
		flow, err := fc.db.UpdateFlowStatus(ctx, database.UpdateFlowStatusParams{
			ID:     flowID,
			Status: database.FlowStatusWaiting,
		})
		if err != nil {
			return fmt.Errorf("failed to renew flow %d status: %w", flowID, err)
		}

		fw, err = LoadFlowWorker(ctx, flow, flowWorkerCtx)
		if err != nil {
			return fmt.Errorf("failed to load flow %d: %w", flowID, err)
		}

		fc.flows[flowID] = fw

		return nil
	}

	if flowID == 0 {
		if err := newFlow(); err != nil {
			return nil, err
		}
	} else if fw, ok = fc.flows[flowID]; ok {
		status, err := fw.GetStatus(ctx)
		if err != nil {
			return nil, fmt.Errorf("failed to get flow %d status: %w", flowID, err)
		}

		switch status {

View on GitHub (pinned to ea665308ba)

Solutions

1. Inspect the wrapped root cause; it names why LoadFlowWorker failed (provider lookup, config, Docker).
2. Restore the provider configuration the flow was created with (API key env vars, server URL).
3. If the flow cannot be rehydrated, start a new flow (flowID=0) instead of resuming this one.
4. Ensure Docker is reachable and the flow's worker container still exists or can be recreated.
5. Verify the stored provider type is still supported after an upgrade.

Example fix

// before
backend restarted with OPENAI_API_KEY unset -> LoadFlowWorker fails
// after
export OPENAI_API_KEY=... (or configure via Settings) then retry CreateAssistant with the same flowID

// confirm the flow's provider is still configured before resuming
if os.Getenv("OPENAI_API_KEY") == "" && flowUsesProvider("openai") {
    return fmt.Errorf("provider credentials missing; cannot resume flow")
}

fw, err := ctl.GetFlow(ctx, flowID)
if err != nil { // ErrFlowNotFound -> worker must be rehydrated
    _, err = ctl.CreateAssistant(ctx, userID, flowID, ...)
    if err != nil { log.Errorf("rehydrate flow %d: %v", flowID, err) }
}

When it happens

Trigger: CreateAssistant on a flowID that is not in fc.flows (e.g. after backend restart) and LoadFlowWorker errors: the stored provider name/type is no longer valid, provider credentials are missing, the configured container/tools are gone, or required config values are absent.

Common situations: Restarting the backend after changing/removing a provider's API key so old flows reference a now-unconfigurable provider; upgrading PentAGI so stored provider types no longer validate; Docker containers from a previous run having been pruned.

Related errors

• failed to get user %d: %w
• failed to renew flow %d status: %w
• failed to get flow %d status: %w
• failed to create assistant: %w
• failed to add assistant to flow: %w

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