What causes "flow %d is in unknown status: %s" in vxcontrol/pentagi?

Inspect the flow row's status value in the database and normalize it to a valid enum value.

flow %d is in unknown status: %s

Error message

flow %d is in unknown status: %s

What it means

Returned by CreateAssistant when the flow's status is not one of the recognized values (Created, Finished, Failed, Running, Waiting). Since all known FlowStatus enum values are handled, this indicates corrupt or out-of-range status data in the database.

Source

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

			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 {
		case database.FlowStatusCreated:
			return nil, fmt.Errorf("flow %d is not completed", flowID)
		case database.FlowStatusFinished, database.FlowStatusFailed:
			if err := loadFlow(); err != nil {
				return nil, err
			}
		case database.FlowStatusRunning, database.FlowStatusWaiting:
			break
		default:
			return nil, fmt.Errorf("flow %d is in unknown status: %s", flowID, status)
		}
	} else {
		if err := loadFlow(); err != nil {
			return nil, err
		}
	}

	if fw == nil { // just double check, this should never happen
		return nil, fmt.Errorf("unexpected error: flow %d not found", flowID)
	}

	aw, err := NewAssistantWorker(ctx, newAssistantWorkerCtx{
		userID:        userID,
		flowID:        flowID,
		input:         input,
		prvname:       prvname,
		prvtype:       prvtype,
		useAgents:     useAgents,

View on GitHub (pinned to ea665308ba)

Solutions

Inspect the flow row's status value in the database and normalize it to a valid enum value.
Align the application binary and migrations to the same version so the status enum matches.
Manually update the row to FlowStatusFailed or FlowStatusWaiting so loadFlow can reset it.
Restore the row from a backup if the data is corrupted.

Example fix

// before
UPDATE flows SET status='pending' WHERE id=42; -- unknown value
// after
UPDATE flows SET status='waiting' WHERE id=42;

Defensive patterns

Strategy: validation

Validate before calling

// sanitize status stored outside the app
SELECT id, status FROM flows WHERE status NOT IN
  ('created','running','finished','failed','waiting');

Type guard

func isKnownFlowStatus(s string) bool {
    switch s {
    case "created", "running", "finished", "failed", "waiting":
        return true
    }
    return false
}

Try / catch

if _, err := ctl.CreateAssistant(...); err != nil {
    if strings.Contains(err.Error(), "unknown status") {
        // fix the row or restore from backup, then retry
    }
}

Prevention

Never hand-edit flow status values in the database.
Keep binary and migrations on the same version.
Constrain the status column to the enum via DB constraints.

When it happens

Trigger: CreateAssistant reads fw.GetStatus and the returned status string matches no case — e.g. a manually edited DB row, a migration that introduced a new enum value the code doesn't know, or binary corruption of the status column.

Common situations: Hand-editing flow status in PostgreSQL, running a newer/older schema than the application binary expects, or data imported from a different version of PentAGI.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

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