vxcontrol/pentagi · error

invalid SubtaskStatus: %s

Error message

invalid SubtaskStatus: %s

What it means

SubtaskStatus is the lifecycle enum for a flow subtask: created, running, waiting, finished, failed. SubtaskStatus.Valid() returns this error for any other value, and the GORM Validate callback runs it on save, so a Subtask with a bad status cannot be persisted.

Source

Thrown at backend/pkg/server/models/subtasks.go:34

	SubtaskStatusFinished SubtaskStatus = "finished"
	SubtaskStatusFailed   SubtaskStatus = "failed"
)

func (s SubtaskStatus) String() string {
	return string(s)
}

// Valid is function to control input/output data
func (s SubtaskStatus) Valid() error {
	switch s {
	case SubtaskStatusCreated,
		SubtaskStatusRunning,
		SubtaskStatusWaiting,
		SubtaskStatusFinished,
		SubtaskStatusFailed:
		return nil
	default:
		return fmt.Errorf("invalid SubtaskStatus: %s", s)
	}
}

// Validate is function to use callback to control input/output data
func (s SubtaskStatus) Validate(db *gorm.DB) {
	if err := s.Valid(); err != nil {
		db.AddError(err)
	}
}

// Subtask is model to contain subtask information
// nolint:lll
type Subtask struct {
	ID          uint64        `form:"id" json:"id" validate:"min=0,numeric" gorm:"type:BIGINT;NOT NULL;PRIMARY_KEY;AUTO_INCREMENT"`
	Status      SubtaskStatus `form:"status" json:"status" validate:"valid,required" gorm:"type:SUBTASK_STATUS;NOT NULL;default:'created'"`
	Title       string        `form:"title" json:"title" validate:"required" gorm:"type:TEXT;NOT NULL"`
	Description string        `form:"description" json:"description" validate:"required" gorm:"type:TEXT;NOT NULL"`
	Context     string        `form:"context" json:"context" validate:"omitempty" gorm:"type:TEXT;NOT NULL;default:''"`

View on GitHub (pinned to ea665308ba)

Solutions

  1. Correct the value to one of: created, running, waiting, finished, failed (constants in backend/pkg/server/models/subtasks.go lines 12-18).
  2. Use the models.SubtaskStatus* constants for all transitions instead of raw strings.
  3. Normalize incoming API status strings (e.g. map 'completed'→'finished') before building the model, or call Valid() early and return a 400.
  4. Fix any bad rows with a data migration before subsequent GORM updates fail.

Example fix

// before
sub := models.Subtask{Status: models.SubtaskStatus("completed")}
// after
sub := models.Subtask{Status: models.SubtaskStatusFinished} // "finished"
Defensive patterns

Strategy: validation

Validate before calling

func isValidSubtaskStatus(v string) bool {
	switch models.SubtaskStatus(v) {
	case models.SubtaskStatusCreated, models.SubtaskStatusRunning,
		models.SubtaskStatusWaiting, models.SubtaskStatusFinished,
		models.SubtaskStatusFailed:
		return true
	}
	return false
}

Type guard

func asSubtaskStatus(v string) (models.SubtaskStatus, bool) {
	s := models.SubtaskStatus(v)
	return s, s.Valid() == nil
}

Try / catch

if err := status.Valid(); err != nil {
	return fmt.Errorf("illegal subtask transition to %q: %w", status, err)
}

Prevention

When it happens

Trigger: Setting Subtask.Status from a state-machine transition that emits an out-of-whitelist string (e.g. 'completed' instead of 'finished', 'in_progress' instead of 'running'); accepting a status from an API payload without normalization; loading legacy rows with pre-rename status values.

Common situations: Deviations from the standard lifecycle names when integrating external tooling that drives subtask state; frontend shorthand ('done' vs 'finished'); SQL data fixes that wrote arbitrary statuses directly into the SUBTASK_STATUS column.

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/31b879ef3a1cdeb8. Report an issue: GitHub.