juanfont/headscale · error

parsing policy from bytes: %w

Error message

parsing policy from bytes: %w

What it means

Error "parsing policy from bytes: %w" thrown in juanfont/headscale.

Source

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

			}

			// 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
			}

			// Non-ASCII tag-name failures surface from Tag.Validate
			// at unmarshal time. Reshape to `tagOwners["tag:X"]: …`.
			if errors.Is(serr.Err, ErrTagNameMustStartWithLetter) {
				ptr := serr.JSONPointer
				name := ptr.LastToken()

				return nil, fmt.Errorf("tagOwners[%q]: %w", name, ErrTagNameMustStartWithLetter)
			}
		}

		return nil, fmt.Errorf("parsing policy from bytes: %w", err)
	}

	if err := policy.validate(); err != nil { //nolint:noinlineerr
		return nil, err
	}

	return &policy, nil
}

// validateProtocolPortCompatibility checks that only TCP, UDP, and SCTP [Protocol]s
// can have specific ports. All other [Protocol]s should only use wildcard ports.
func validateProtocolPortCompatibility(protocol Protocol, destinations []AliasWithPorts) error {
	// Only TCP, UDP, and SCTP support specific ports
	supportsSpecificPorts := protocol == ProtocolNameTCP || protocol == ProtocolNameUDP || protocol == ProtocolNameSCTP || protocol == ""

	if supportsSpecificPorts {
		return nil // No validation needed for these protocols
	}

View on GitHub (pinned to 565fd254d0)

Solutions

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

When it happens

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

Common situations: Loading the policy from raw bytes failed. Verify the policy content is valid HuJSON and matches the expected schema.

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