juanfont/headscale · error

type not supported

Error message

type not supported

What it means

Thrown at hscontrol/policy/v2/types.go:912 and 978 when hostport/alias decoding encounters a JSON value whose Go type is not handled by the parser; the error includes the concrete %T. This is a shape error — the JSON structure is wrong for the field, not merely a bad string.

Source

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

// point operators at the issue.
var nodeAttrUnsupportedCaps = map[tailcfg.NodeCapability]string{
	tailcfg.NodeAttrFunnel: "https://github.com/juanfont/headscale/issues/2527",
}

// Policy validation errors.
var (
	ErrInvalidUsername             = errors.New("username must contain @")
	ErrUserNotFound                = errors.New("user not found")
	ErrMultipleUsersFound          = errors.New("multiple users found")
	ErrInvalidGroupFormat          = errors.New("group must start with 'group:'")
	ErrInvalidTagFormat            = errors.New("tag must start with 'tag:'")
	ErrInvalidHostname             = errors.New("invalid hostname")
	ErrHostResolve                 = errors.New("error resolving host")
	ErrInvalidPrefix               = errors.New("invalid prefix")
	ErrInvalidAutogroup            = errors.New("invalid autogroup")
	ErrUnknownAutogroup            = errors.New("unknown autogroup")
	ErrHostportMissingColon        = errors.New("hostport must contain a colon")
	ErrTypeNotSupported            = errors.New("type not supported")
	ErrInvalidAlias                = errors.New("invalid alias format")
	ErrInvalidAutoApprover         = errors.New("invalid auto approver format")
	ErrInvalidOwner                = errors.New("invalid owner format")
	ErrGroupNotDefined             = errors.New("group not defined in policy")
	ErrInvalidGroupMember          = errors.New("invalid group member type")
	ErrGroupValueNotArray          = errors.New("group value must be an array of users")
	ErrInvalidHostIP               = errors.New("hostname contains invalid IP address")
	ErrTagNotDefined               = errors.New("tag not found")
	ErrAutoApproverNotAlias        = errors.New("auto approver is not an alias")
	ErrInvalidACLAction            = errors.New("invalid ACL action")
	ErrInvalidSSHAction            = errors.New("invalid SSH action")
	ErrInvalidProtocolNumber       = errors.New("invalid protocol number")
	ErrProtocolLeadingZero         = errors.New("leading 0 not permitted in protocol number")
	ErrProtocolOutOfRange          = errors.New("protocol number out of range (0-255)")
	ErrAutogroupNotSupported       = errors.New("autogroup not supported in headscale")
	ErrAutogroupInternetSrc        = errors.New("autogroup:internet can only be used in ACL destinations")
	ErrAutogroupSelfSrc            = errors.New("\"autogroup:self\" not valid on the src side of a rule")
	ErrAutogroupNotSupportedACLSrc = errors.New("autogroup not supported for ACL sources")

View on GitHub (pinned to 565fd254d0)

Solutions

1. Make every alias/src/dst entry a JSON string
2. Inspect the %T in the error to see which field has the wrong type
3. Generate policies with json.Marshal of the headscale policy types, not hand-built maps

Example fix

// before
{"acls": [{"action": "accept", "src": ["group:admins"], "dst": [443]}]}
// after
{"acls": [{"action": "accept", "src": ["group:admins"], "dst": ["*:443"]}]}

// generated policies: assert alias slices are all strings
for _, a := range append(rule.Src, rule.Dst...) {
    if reflect.TypeOf(a).Kind() != reflect.String {
        return fmt.Errorf("alias must be string, got %T", a)
    }
}

func isStringAlias(v any) bool { _, ok := v.(string); return ok }

if errors.Is(err, policy.ErrTypeNotSupported) {
    // %T in message names the offending JSON type; fix the generator
}

When it happens

Trigger: Passing a number or object where a string alias is expected, e.g. {"dst": [443]} or {"src": {"user": "alice"}} in a policy fed through the JSON path; also API callers unmarshalling policy JSON with mismatched types. The parser switch hits default and reports the type.

Common situations: Programmatic policy generation emitting numbers for ports/aliases; hand-editing HuJSON into invalid JSON shapes; a frontend or API client serializing aliases as objects instead of strings.

Related errors

• %w: %T
• invalid action
• test(s) failed
• nodeAttrs target does not support this autogroup
• username must contain @

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