Upgrading HeadScale from 0.28 to 0.29.1

June 26, 2026

I’ve been running headscale for a bit and getting it setup to start with had it’s challenges, but I figured it out. Partly due to the excellent error messages posted by the software as it starts up.

Recently there was an update with at least one breaking change in it.

It’s simple to fix if you read the error on the console and THEN read the release notes, but looking through the release notes under “Breaking” there’s a long list of stuff and the specific fix that worked for my very basic setup was very simple and not obvious.

The Problem

In the config.yaml file there’s a line that calls for a random port for wireguard access (or not).

randomize_client_port: true

This is deprecated in the 0.29 version of headscale.

The Solution

Instead you need a new file added where the system can see it (I put it where other paths in the config file show it will land where I can see it in my docker volumes). This is the policy file. If you’re like me then it’s likely your policies are pretty thin (I didn’t have any). In the config file in the policy section mine looked like this before the fix.

policy:
 mode: database
 path: ""

I changed it to

policy:
 mode: file
 path: "path/to/my/policy.file"

Then I created the file in the right place and put

{
 "randomizeClientPort": true,
}

In the file, nothing else.

Docker compose up, and all started up as it should. No errors, no issues. Testing shows it working as expected.