juanfont/headscale · error

parsing HuJSON: %w

Error message

parsing HuJSON: %w

What it means

Error "parsing HuJSON: %w" thrown in juanfont/headscale.

Source

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

	*u = SSHUser(strings.TrimSpace(s))

	return nil
}

// unmarshalPolicy takes a byte slice and unmarshals it into a [Policy] struct.
// In addition to unmarshalling, it will also validate the policy.
// This is the only entrypoint of reading a policy from a file or other source.
func unmarshalPolicy(b []byte) (*Policy, error) {
	if len(b) == 0 {
		return nil, nil //nolint:nilnil // intentional: no policy when empty input
	}

	var policy Policy

	ast, err := hujson.Parse(b)
	if err != nil {
		return nil, fmt.Errorf("parsing HuJSON: %w", err)
	}

	ast.Standardize()

	if err = json.Unmarshal(ast.Pack(), &policy, policyJSONOpts...); err != nil { //nolint:noinlineerr
		if serr, ok := errors.AsType[*json.SemanticError](err); ok {
			if errors.Is(serr.Err, json.ErrUnknownName) {
				ptr := serr.JSONPointer
				name := ptr.LastToken()

				return nil, fmt.Errorf("%w: %q", ErrUnknownField, name)
			}

			// Non-tag entries in grant.via surface as type errors on
			// []Tag; rephrase to the wire-compatible body.
			if strings.Contains(string(serr.JSONPointer), "/via/") {
				return nil, ErrGrantViaNotATag
			}

View on GitHub (pinned to 565fd254d0)

Solutions

1. Inspect the wrapped error for the underlying cause and correct the failing condition (parsing HuJSON); 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 (parsing HuJSON); retry the operation after fixing the input, configuration, or environment.

When it happens

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

Common situations: The policy file is not valid HuJSON. Fix syntax errors (trailing commas are allowed, but malformed objects/arrays are not).

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