starred/headscale
1
0
Fork 0
mirror of https://github.com/juanfont/headscale.git synced 2026-01-11 20:00:28 +01:00
Code Issues 98 Packages Projects Releases 10 Wiki Activity

[Bug] Error parsing ACL entry "randomizeClientPort" in 0.27.1 #1152

New Issue
Closed
opened 2025-12-29 02:28:35 +01:00 by adam · 2 comments
adam commented 2025-12-29 02:28:35 +01:00
Owner
Copy Link

Originally created by @leriak on GitHub (Nov 17, 2025).

Is this a support request?

  • This is not a support request

Is there an existing issue for this?

  • I have searched the existing issues

Current Behavior

I have several nodes behind an Opnsense router, and I have set "randomizeClientPort" : true in ACL as per tailscale documentation here to help with establishing direct connections. This has been working fine for a while in version 0.26.1.

I have tried upgrading to 0.27.1 and after the upgrade headscale won't start, here are the logs (from docker):

headscale exited with code 1 (restarting)
headscale  | 2025-11-17T16:57:33Z INF Opening database database=sqlite3 path=/var/lib/headscale/db.sqlite
headscale  | 2025-11-17T16:57:33Z INF Starting schema recreation with table renaming
headscale  | 2025-11-17T16:57:33Z INF Schema recreation completed successfully
headscale  | 2025-11-17T16:57:33Z FTL home/runner/work/headscale/headscale/cmd/headscale/cli/serve.go:32 > Error initializing error="creating new headscale: init state: init policy manager: parsing policy: unknown field \"randomizeClientPort\""
headscale  | 2025-11-17T16:57:34Z INF Opening database database=sqlite3 path=/var/lib/headscale/db.sqlite
headscale  | 2025-11-17T16:57:34Z INF Opening database database=sqlite3 path=/var/lib/headscale/db.sqlite
headscale  | 2025-11-17T16:57:34Z FTL home/runner/work/headscale/headscale/cmd/headscale/cli/serve.go:32 > Error initializing error="creating new headscale: init state: init policy manager: parsing policy: unknown field \"randomizeClientPort\""
headscale  | 2025-11-17T16:57:34Z FTL home/runner/work/headscale/headscale/cmd/headscale/cli/serve.go:32 > Error initializing error="creating new headscale: init state: init policy manager: parsing policy: unknown field \"randomizeClientPort\""
headscale exited with code 1 (restarting)
headscale  | 2025-11-17T16:57:34Z INF Opening database database=sqlite3 path=/var/lib/headscale/db.sqlite
headscale  | 2025-11-17T16:57:34Z FTL home/runner/work/headscale/headscale/cmd/headscale/cli/serve.go:32 > Error initializing error="creating new headscale: init state: init policy manager: parsing policy: unknown field \"randomizeClientPort\""
headscale exited with code 1 (restarting)

Then I have reverted to 0.26.1 using a backup, removed (commented out) the "randomizeClientPort" : true entry and upgraded to 0.27.1 again, now headscale starts without error, here are the logs:

headscale  | 2025-11-17T17:00:46Z INF Opening database database=sqlite3 path=/var/lib/headscale/db.sqlite
headscale  | 2025-11-17T17:00:46Z INF Starting schema recreation with table renaming
headscale  | 2025-11-17T17:00:46Z INF Schema recreation completed successfully
headscale  | 2025-11-17T17:00:46Z INF Starting Headscale commit=f658a8eacd4d86edc65424b50635afed46ca4b2a version=v0.27.1+dirty
headscale  | 2025-11-17T17:00:46Z INF Clients with a lower minimum version will be rejected minimum_version=v1.64.0
headscale  | 2025-11-17T17:00:46Z WRN Listening without TLS but ServerURL does not start with http://
headscale  | 2025-11-17T17:00:46Z INF listening and serving HTTP on: 0.0.0.0:8080
headscale  | 2025-11-17T17:00:46Z INF listening and serving debug and metrics on: 127.0.0.1:9090

With 0.27.1 running I have tried to add the "randomizeClientPort" : true entry again, but received an error, here is the log (Headplane in docker):

headplane  | ResponseError: Response Error (500): {"code":2, "message":"setting policy: parsing policy: unknown field \"randomizeClientPort\"", "details":[]}
headplane  |     at ApiClient.put (file:///app/build/server/assets/api-client-DTldznvl.js:186:10)
headplane  |     at process.processTicksAndRejections (node:internal/process/task_queues:105:5)
headplane  |     at async aclAction (file:///app/build/server/assets/server-build.js:4389:33)
headplane  |     at async callRouteHandler (file:///app/node_modules/.pnpm/react-router@7.8.1_react-dom@19.1.1_react@19.1.1__react@19.1.1/node_modules/react-router/dist/development/chunk-IFMMFE4R.mjs:509:16)
headplane  |     at async file:///app/node_modules/.pnpm/react-router@7.8.1_react-dom@19.1.1_react@19.1.1__react@19.1.1/node_modules/react-router/dist/development/chunk-UH6JLGW7.mjs:4327:19
headplane  |     at async callLoaderOrAction (file:///app/node_modules/.pnpm/react-router@7.8.1_react-dom@19.1.1_react@19.1.1__react@19.1.1/node_modules/react-router/dist/development/chunk-UH6JLGW7.mjs:4379:16)
headplane  |     at async Promise.all (index 0)
headplane  |     at async defaultDataStrategy (file:///app/node_modules/.pnpm/react-router@7.8.1_react-dom@19.1.1_react@19.1.1__react@19.1.1/node_modules/react-router/dist/development/chunk-UH6JLGW7.mjs:3940:17)
headplane  |     at async callDataStrategyImpl (file:///app/node_modules/.pnpm/react-router@7.8.1_react-dom@19.1.1_react@19.1.1__react@19.1.1/node_modules/react-router/dist/development/chunk-UH6JLGW7.mjs:4275:17)
headplane  |     at async callDataStrategy (file:///app/node_modules/.pnpm/react-router@7.8.1_react-dom@19.1.1_react@19.1.1__react@19.1.1/node_modules/react-router/dist/development/chunk-UH6JLGW7.mjs:3273:19) {
headplane  |   status: 500,
headplane  |   response: '{"code":2, "message":"setting policy: parsing policy: unknown field \\"randomizeClientPort\\"", "details":[]}',
headplane  |   responseObject: {
headplane  |     code: 2,
headplane  |     message: 'setting policy: parsing policy: unknown field "randomizeClientPort"',
headplane  |     details: []
headplane  |   }
headplane  | }

Headscale works without setting "randomizeClientPort": true but I no longer get direct connections to the nodes behind the Opnsense firewall when outside the lan on the firewall, while on headscale 0.26.1 with "randomizeClientPort": true I always get direct connection., so for the time being I have reverted to headscale 0.26.1

Expected Behavior

Allow "randomizeClientPort" to be set in ACL

Steps To Reproduce

  1. In headscale 0.26.1 set "randomizeClientPort" : true in ACL
  2. Upgrade to headscale 0.27.1
    or
  3. In headscale 0.27.1 try to set "randomizeClientPort" : true in ACL

Environment

- OS:Debian 13 (Docker 29.0.1)
- Headscale version: 0.26.1 and 0.27.1
- Tailscale version: 1.90.4 (android) and 1.90.6 (linux)
- Number of nodes: 8
- GUI: Headplane 0.6.1

Runtime environment

  • Headscale is behind a (reverse) proxy
  • Headscale runs in a container

Debug information

See headscale and headplane logs above

Originally created by @leriak on GitHub (Nov 17, 2025). ### Is this a support request? - [x] This is not a support request ### Is there an existing issue for this? - [x] I have searched the existing issues ### Current Behavior I have several nodes behind an Opnsense router, and I have set `"randomizeClientPort" : true` in ACL as per tailscale documentation [here](https://tailscale.com/kb/1097/install-opnsense) to help with establishing direct connections. This has been working fine for a while in version 0.26.1. I have tried upgrading to 0.27.1 and after the upgrade headscale won't start, here are the logs (from docker): ``` headscale exited with code 1 (restarting) headscale | 2025-11-17T16:57:33Z INF Opening database database=sqlite3 path=/var/lib/headscale/db.sqlite headscale | 2025-11-17T16:57:33Z INF Starting schema recreation with table renaming headscale | 2025-11-17T16:57:33Z INF Schema recreation completed successfully headscale | 2025-11-17T16:57:33Z FTL home/runner/work/headscale/headscale/cmd/headscale/cli/serve.go:32 > Error initializing error="creating new headscale: init state: init policy manager: parsing policy: unknown field \"randomizeClientPort\"" headscale | 2025-11-17T16:57:34Z INF Opening database database=sqlite3 path=/var/lib/headscale/db.sqlite headscale | 2025-11-17T16:57:34Z INF Opening database database=sqlite3 path=/var/lib/headscale/db.sqlite headscale | 2025-11-17T16:57:34Z FTL home/runner/work/headscale/headscale/cmd/headscale/cli/serve.go:32 > Error initializing error="creating new headscale: init state: init policy manager: parsing policy: unknown field \"randomizeClientPort\"" headscale | 2025-11-17T16:57:34Z FTL home/runner/work/headscale/headscale/cmd/headscale/cli/serve.go:32 > Error initializing error="creating new headscale: init state: init policy manager: parsing policy: unknown field \"randomizeClientPort\"" headscale exited with code 1 (restarting) headscale | 2025-11-17T16:57:34Z INF Opening database database=sqlite3 path=/var/lib/headscale/db.sqlite headscale | 2025-11-17T16:57:34Z FTL home/runner/work/headscale/headscale/cmd/headscale/cli/serve.go:32 > Error initializing error="creating new headscale: init state: init policy manager: parsing policy: unknown field \"randomizeClientPort\"" headscale exited with code 1 (restarting) ``` Then I have reverted to 0.26.1 using a backup, removed (commented out) the `"randomizeClientPort" : true` entry and upgraded to 0.27.1 again, now headscale starts without error, here are the logs: ``` headscale | 2025-11-17T17:00:46Z INF Opening database database=sqlite3 path=/var/lib/headscale/db.sqlite headscale | 2025-11-17T17:00:46Z INF Starting schema recreation with table renaming headscale | 2025-11-17T17:00:46Z INF Schema recreation completed successfully headscale | 2025-11-17T17:00:46Z INF Starting Headscale commit=f658a8eacd4d86edc65424b50635afed46ca4b2a version=v0.27.1+dirty headscale | 2025-11-17T17:00:46Z INF Clients with a lower minimum version will be rejected minimum_version=v1.64.0 headscale | 2025-11-17T17:00:46Z WRN Listening without TLS but ServerURL does not start with http:// headscale | 2025-11-17T17:00:46Z INF listening and serving HTTP on: 0.0.0.0:8080 headscale | 2025-11-17T17:00:46Z INF listening and serving debug and metrics on: 127.0.0.1:9090 ``` With 0.27.1 running I have tried to add the `"randomizeClientPort" : true` entry again, but received an error, here is the log (Headplane in docker): ``` headplane | ResponseError: Response Error (500): {"code":2, "message":"setting policy: parsing policy: unknown field \"randomizeClientPort\"", "details":[]} headplane | at ApiClient.put (file:///app/build/server/assets/api-client-DTldznvl.js:186:10) headplane | at process.processTicksAndRejections (node:internal/process/task_queues:105:5) headplane | at async aclAction (file:///app/build/server/assets/server-build.js:4389:33) headplane | at async callRouteHandler (file:///app/node_modules/.pnpm/react-router@7.8.1_react-dom@19.1.1_react@19.1.1__react@19.1.1/node_modules/react-router/dist/development/chunk-IFMMFE4R.mjs:509:16) headplane | at async file:///app/node_modules/.pnpm/react-router@7.8.1_react-dom@19.1.1_react@19.1.1__react@19.1.1/node_modules/react-router/dist/development/chunk-UH6JLGW7.mjs:4327:19 headplane | at async callLoaderOrAction (file:///app/node_modules/.pnpm/react-router@7.8.1_react-dom@19.1.1_react@19.1.1__react@19.1.1/node_modules/react-router/dist/development/chunk-UH6JLGW7.mjs:4379:16) headplane | at async Promise.all (index 0) headplane | at async defaultDataStrategy (file:///app/node_modules/.pnpm/react-router@7.8.1_react-dom@19.1.1_react@19.1.1__react@19.1.1/node_modules/react-router/dist/development/chunk-UH6JLGW7.mjs:3940:17) headplane | at async callDataStrategyImpl (file:///app/node_modules/.pnpm/react-router@7.8.1_react-dom@19.1.1_react@19.1.1__react@19.1.1/node_modules/react-router/dist/development/chunk-UH6JLGW7.mjs:4275:17) headplane | at async callDataStrategy (file:///app/node_modules/.pnpm/react-router@7.8.1_react-dom@19.1.1_react@19.1.1__react@19.1.1/node_modules/react-router/dist/development/chunk-UH6JLGW7.mjs:3273:19) { headplane | status: 500, headplane | response: '{"code":2, "message":"setting policy: parsing policy: unknown field \\"randomizeClientPort\\"", "details":[]}', headplane | responseObject: { headplane | code: 2, headplane | message: 'setting policy: parsing policy: unknown field "randomizeClientPort"', headplane | details: [] headplane | } headplane | } ``` Headscale works without setting `"randomizeClientPort": true` but I no longer get direct connections to the nodes behind the Opnsense firewall when outside the lan on the firewall, while on headscale 0.26.1 with `"randomizeClientPort": true` I always get direct connection., so for the time being I have reverted to headscale 0.26.1 ### Expected Behavior Allow "randomizeClientPort" to be set in ACL ### Steps To Reproduce 1. In headscale 0.26.1 set "randomizeClientPort" : true in ACL 2. Upgrade to headscale 0.27.1 or 1. In headscale 0.27.1 try to set "randomizeClientPort" : true in ACL ### Environment ```markdown - OS:Debian 13 (Docker 29.0.1) - Headscale version: 0.26.1 and 0.27.1 - Tailscale version: 1.90.4 (android) and 1.90.6 (linux) - Number of nodes: 8 - GUI: Headplane 0.6.1 ``` ### Runtime environment - [x] Headscale is behind a (reverse) proxy - [x] Headscale runs in a container ### Debug information See headscale and headplane logs above
adam added the bug label 2025-12-29 02:28:35 +01:00
adam closed this issue 2025-12-29 02:28:35 +01:00
adam commented 2025-12-29 02:28:35 +01:00
Author
Owner
Copy Link

@nblock commented on GitHub (Nov 18, 2025):

and I have set "randomizeClientPort" : true in ACL as per tailscale documentation here to help with establishing direct connections.

In Headscale, the option to randomize the client port is specified via the configuration file:

# Enabling this option makes devices prefer a random port for WireGuard traffic over the
# default static port 41641. This option is intended as a workaround for some buggy
# firewall devices. See https://tailscale.com/kb/1181/firewalls/ for more information.
randomize_client_port: false
@nblock commented on GitHub (Nov 18, 2025): > and I have set "randomizeClientPort" : true in ACL as per tailscale documentation [here](https://tailscale.com/kb/1097/install-opnsense) to help with establishing direct connections. In Headscale, the option to randomize the client port is specified [via the configuration file](https://github.com/juanfont/headscale/blob/v0.27.1/config-example.yaml#L406-L409): ```yaml # Enabling this option makes devices prefer a random port for WireGuard traffic over the # default static port 41641. This option is intended as a workaround for some buggy # firewall devices. See https://tailscale.com/kb/1181/firewalls/ for more information. randomize_client_port: false ```
adam commented 2025-12-29 02:28:35 +01:00
Author
Owner
Copy Link

@leriak commented on GitHub (Nov 19, 2025):

Thank you very much. I have already upgraded and setting this up in config.yaml now direct connections are happening.

I read the whole file as I was setting Headscale up, but as I didn't know I needed it I must have forgotten about it when I found the Tailscale page where it suggested to set this in ACL.

@leriak commented on GitHub (Nov 19, 2025): Thank you very much. I have already upgraded and setting this up in config.yaml now direct connections are happening. I read the whole file as I was setting Headscale up, but as I didn't know I needed it I must have forgotten about it when I found the Tailscale page where it suggested to set this in ACL.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
CLI
DERP
DNS
Nix
OIDC
SSH
bug
database
documentation
duplicate
enhancement
faq
good first issue
grants
help wanted
might-come
needs design doc
needs investigation
no-stale-bot
out of scope
performance
policy 📝
pull-request
Mirrored from GitHub Pull Request
 question
regression
routes
stale
tags
tailscale-feature-gap
well described ❤️
wontfix
No Label bug
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
adam
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: starred/headscale#1152
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?