GoogleContainerTools/skaffold · error

unknown Phase %v not found in handler state

Error message

unknown Phase %v not found in handler state

What it means

AutoTriggerDiff compares a desired auto-trigger value against handler state for a given phase (Build/Sync/Deploy). If the phase argument is not one of the constants the state machine tracks, the switch's default branch returns this error. It signals a programming/API misuse: a Phase value that does not exist in the handler's state.

Source

Thrown at pkg/skaffold/event/v2/state.go:167

	handler.setState(newState)
}

func UpdateStateAutoSyncTrigger(t bool) {
	newState := handler.getState()
	newState.FileSyncState.AutoTrigger = t
	handler.setState(newState)
}

func AutoTriggerDiff(phase constants.Phase, val bool) (bool, error) {
	switch phase {
	case constants.Build:
		return val != handler.getState().BuildState.AutoTrigger, nil
	case constants.Sync:
		return val != handler.getState().FileSyncState.AutoTrigger, nil
	case constants.Deploy:
		return val != handler.getState().DeployState.AutoTrigger, nil
	default:
		return false, fmt.Errorf("unknown Phase %v not found in handler state", phase)
	}
}

View on GitHub (pinned to a1189de023)

Solutions

1. Pass only constants.Build, constants.Sync, or constants.Deploy to AutoTriggerDiff.
2. Add a case for the new Phase constant to AutoTriggerDiff if you genuinely added a new phase.
3. Validate/whitelist the phase value before calling, returning a clear error to the caller.

Example fix

// before
same, err := event.AutoTriggerDiff(constants.Test, true)
// after
if phase != constants.Build && phase != constants.Sync && phase != constants.Deploy {
    return fmt.Errorf("unsupported phase %q for auto-trigger", phase)
}
same, err := event.AutoTriggerDiff(phase, true)

func isValidPhase(phase constants.Phase) bool {
    switch phase {
    case constants.Build, constants.Sync, constants.Deploy:
        return true
    }
    return false
}
// call only if isValidPhase(phase)

func isTriggerablePhase(phase constants.Phase) bool {
    switch phase {
    case constants.Build, constants.Sync, constants.Deploy:
        return true
    default:
        return false
    }
}

same, err := event.AutoTriggerDiff(phase, desired)
if err != nil {
    if strings.Contains(err.Error(), "unknown Phase") {
        return fmt.Errorf("phase %q does not support auto-trigger: %w", phase, err)
    }
    return err
}

When it happens

Trigger: Calling AutoTriggerDiff with a phase string that is not constants.Build, constants.Sync, or constants.Deploy — e.g. constants.Init, constants.DevLoop, an empty string, a typo, or a phase added in a newer version but not handled here.

Common situations: Wiring the auto-trigger UI/API to a new skaffold Phase without updating AutoTriggerDiff; comparing against an unexported/renamed constant after an upgrade; passing user-supplied phase names without validation.

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

• cannot call Run with empty container config
• unable to create directory %q: %w
• opening %s: %w
• marshalling event: %w
• writing string: %w

AI-assisted analysis of GoogleContainerTools/skaffold@a1189de023 (2026-09-05). Data as JSON: /api/errors/cd2825437241f6f8. Report an issue: GitHub.