juanfont/headscale · error · ErrSSHCheckPeriodNegative

checkPeriod %s %w

Error message

checkPeriod %s %w

What it means

Error "checkPeriod %s %w" thrown in juanfont/headscale.

Source

Thrown at hscontrol/policy/v2/types.go:2859

// MarshalJSON implements JSON marshaling for [SSHCheckPeriod].
func (p SSHCheckPeriod) MarshalJSON() ([]byte, error) {
	if p.Always {
		return []byte(`"always"`), nil
	}

	return fmt.Appendf(nil, "%q", p.Duration.String()), nil
}

// Validate rejects negative durations and anything above the inclusive
// 168h max.
func (p *SSHCheckPeriod) Validate() error {
	if p.Always {
		return nil
	}

	if p.Duration < 0 {
		return fmt.Errorf("checkPeriod %s %w", p.Duration, ErrSSHCheckPeriodNegative)
	}

	if p.Duration > SSHCheckPeriodMax {
		return fmt.Errorf("checkPeriod %s %w", p.Duration, ErrSSHCheckPeriodAboveMax)
	}

	return nil
}

// SSH controls who can ssh into which machines.
type SSH struct {
	Action       SSHAction       `json:"action"`
	Sources      SSHSrcAliases   `json:"src"`
	Destinations SSHDstAliases   `json:"dst"`
	Users        SSHUsers        `json:"users"`
	CheckPeriod  *SSHCheckPeriod `json:"checkPeriod,omitempty"`
	AcceptEnv    []string        `json:"acceptEnv,omitempty"`
}

View on GitHub (pinned to 565fd254d0)

Solutions

1. Inspect the wrapped error for the underlying cause and correct the failing condition (checkPeriod); retry the operation after fixing the input, configuration, or environment.

Example fix

Inspect the wrapped error for the underlying cause and correct the failing condition (checkPeriod); retry the operation after fixing the input, configuration, or environment.

When it happens

Trigger: Thrown at hscontrol/policy/v2/types.go:2859 when the library encounters an invalid state.

Common situations: The SSH check rule's checkPeriod value is invalid. Use a positive duration no greater than 168h, and only with action "check".

AI-assisted analysis of juanfont/headscale@565fd254d0 (2026-08-15). Data as JSON: /api/errors/76bae0d7576227e8. Report an issue: GitHub.