juanfont/headscale · error

marshalling machine key: %w

Error message

marshalling machine key: %w

What it means

Error from 'headscale generate private-key' when MachineKey.MarshalText fails while serializing a freshly generated key.NewMachine() value. MarshalText on a machine key encodes it to its text (base64-style) form; it fails only if the underlying key data cannot be encoded, which for a newly generated key is effectively unreachable defensive error handling.

Source

Thrown at cmd/headscale/cli/generate.go:29

	rootCmd.AddCommand(generateCmd)
	generateCmd.AddCommand(generatePrivateKeyCmd)
}

var generateCmd = &cobra.Command{
	Use:     "generate",
	Short:   "Generate commands",
	Aliases: []string{"gen"},
}

var generatePrivateKeyCmd = &cobra.Command{
	Use:   "private-key",
	Short: "Generate a private key for the headscale server",
	RunE: func(cmd *cobra.Command, args []string) error {
		machineKey := key.NewMachine()

		machineKeyStr, err := machineKey.MarshalText()
		if err != nil {
			return fmt.Errorf("marshalling machine key: %w", err)
		}

		return printOutput(cmd, map[string]string{
			"private_key": string(machineKeyStr),
		},
			string(machineKeyStr))
	},
}

View on GitHub (pinned to 565fd254d0)

Solutions

1. Rerun the command — a transient occurrence points to toolchain/binary corruption, not config
2. Rebuild the binary from clean sources (make clean && make build)
3. Verify the tailscale key package is unmodified if running a fork

if _, err := machineKey.MarshalText(); err != nil {
	// practically unreachable; regenerate rather than handle
	machineKey = key.NewMachine()
}

When it happens

Trigger: Practically never: it would require key.NewMachine to produce data the encoder rejects (zero-length or malformed key), which the constructor prevents. Seen only as noise in code paths that must satisfy the error-returning MarshalText API.

Common situations: None realistically; if it ever appears, suspect memory corruption or a patched/forked key package rather than operational misconfiguration.

Related errors

• generating salt: %w
• MOCKOIDC_CLIENT_ID not defined
• failed to parse ApiKey
• failed to generate API key
• node not found

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