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

[Bug] Remote CLI Configuration Problem after Upgrading to Headscale 0.23.0 #831

New Issue
Closed
opened 2025-12-29 02:24:36 +01:00 by adam · 4 comments
adam commented 2025-12-29 02:24:36 +01:00
Owner
Copy Link

Originally created by @chuangbo on GitHub (Oct 12, 2024).

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

After upgrading from Headscale 0.23.0 beta 3 to 0.23.0, the remote CLI command headscale nodes list fails with the following error:

github.com/juanfont/headscale@v0.23.0/cmd/headscale/cli/root.go:49 > Error loading config error="fatal error reading config file: Config File \"config\" Not Found in \"[/etc/headscale /Users/user/.headscale]\""

This occurs even when HEADSCALE_CLI_ADDRESS and HEADSCALE_CLI_API_KEY environment variables are correctly set.

Expected Behavior

The remote CLI should function properly when either of the following conditions are met:

  • The HEADSCALE_CLI_ADDRESS and HEADSCALE_CLI_API_KEY environment variables are set correctly, without requiring an additional configuration file.
  • A configuration file (~/.headscale/config.yaml or /etc/headscale/config.yaml) is present with the correct CLI settings.

The remote CLI should be able to connect to the Headscale server and execute commands (such as headscale nodes list) without encountering configuration-related errors, regardless of whether the configuration is provided via environment variables or a configuration file.

Steps To Reproduce

  • Upgrade Headscale from version 0.23.0 beta 3 to 0.23.0
  • Set HEADSCALE_CLI_ADDRESS and HEADSCALE_CLI_API_KEY environment variables, without any additional configuration files.
  • Run headscale nodes list
  • Observe the error message

Environment

- OS: macOS 15.0
- Headscale version: 0.23.0
- Tailscale version: 1.74.0

Runtime environment

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

Anything else?

Workarounds

Two workarounds have been identified:

  1. Keep the environment variables HEADSCALE_CLI_ADDRESS and HEADSCALE_CLI_API_KEY and create an empty file at ~/.headscale/config.yaml
  2. Remove the environment variables and create a ~/.headscale/config.yaml file with the following content:
cli:
  address: headscale.example.com
  api_key: MY_API_KEY

Possible Cause

The issue may be related to commit 8a3a0fe, which removed the IsCLIConfigured check in hscontrol/types/config.go.

Proposed Solutions

We have two potential solutions to address this issue:

  1. Update the documentation in docs/ref/remote-cli.md to recommend using a configuration file instead of environment variables.
  2. Revert to the previous behavior that allowed the use of environment variables without a configuration file.

Questions

  1. Which solution do you prefer: updating the documentation or reverting the behavior?
  2. Would you like me to submit a PR to implement the chosen solution?
Originally created by @chuangbo on GitHub (Oct 12, 2024). ### 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 After upgrading from Headscale 0.23.0 beta 3 to 0.23.0, the remote CLI command headscale nodes list fails with the following error: `github.com/juanfont/headscale@v0.23.0/cmd/headscale/cli/root.go:49 > Error loading config error="fatal error reading config file: Config File \"config\" Not Found in \"[/etc/headscale /Users/user/.headscale]\""` This occurs even when `HEADSCALE_CLI_ADDRESS` and `HEADSCALE_CLI_API_KEY` environment variables are correctly set. ### Expected Behavior The remote CLI should function properly when either of the following conditions are met: * The `HEADSCALE_CLI_ADDRESS` and `HEADSCALE_CLI_API_KEY` environment variables are set correctly, without requiring an additional configuration file. * A configuration file (`~/.headscale/config.yaml` or `/etc/headscale/config.yaml`) is present with the correct CLI settings. The remote CLI should be able to connect to the Headscale server and execute commands (such as `headscale nodes list`) without encountering configuration-related errors, regardless of whether the configuration is provided via environment variables or a configuration file. ### Steps To Reproduce * Upgrade Headscale from version 0.23.0 beta 3 to 0.23.0 * Set `HEADSCALE_CLI_ADDRESS` and `HEADSCALE_CLI_API_KEY` environment variables, without any additional configuration files. * Run `headscale nodes list` * Observe the error message ### Environment ```markdown - OS: macOS 15.0 - Headscale version: 0.23.0 - Tailscale version: 1.74.0 ``` ### Runtime environment - [ ] Headscale is behind a (reverse) proxy - [ ] Headscale runs in a container ### Anything else? ### Workarounds Two workarounds have been identified: 1. Keep the environment variables `HEADSCALE_CLI_ADDRESS` and `HEADSCALE_CLI_API_KEY` and create an empty file at `~/.headscale/config.yaml` 2. Remove the environment variables and create a `~/.headscale/config.yaml` file with the following content: ```yaml cli: address: headscale.example.com api_key: MY_API_KEY ``` ### Possible Cause The issue may be related to commit [8a3a0fe](https://github.com/juanfont/headscale/commit/8a3a0fee3ccbca7dd67b0d2965b523c8b6cb5451#diff-077ec63c2c0a08956c63c365aa4953cf65d09cf7e62c74747336fca3c308f6d6L287-L290), which removed the `IsCLIConfigured` check in `hscontrol/types/config.go`. ### Proposed Solutions We have two potential solutions to address this issue: 1. Update the documentation in `docs/ref/remote-cli.md` to recommend using a configuration file instead of environment variables. 2. Revert to the previous behavior that allowed the use of environment variables without a configuration file. ### Questions 1. Which solution do you prefer: updating the documentation or reverting the behavior? 2. Would you like me to submit a PR to implement the chosen solution?
adam added the stalebug labels 2025-12-29 02:24:36 +01:00
adam closed this issue 2025-12-29 02:24:36 +01:00
adam commented 2025-12-29 02:24:36 +01:00
Author
Owner
Copy Link

@nblock commented on GitHub (Oct 26, 2024):

I can confirm your issue and have a small addition to your workaround:

  • an empty config.yaml in one of the config lookup paths or
  • an empty file and headscale -c /path/to/empty.yaml

is sufficient to use the settings from the environment variables.

Still, both methods to configure the gRPC connection should be equally supported.

@nblock commented on GitHub (Oct 26, 2024): I can confirm your issue and have a small addition to your workaround: - an empty `config.yaml` in one of the config lookup paths _or_ - an empty file and `headscale -c /path/to/empty.yaml` is sufficient to use the settings from the environment variables. Still, both methods to configure the gRPC connection should be equally supported.
adam commented 2025-12-29 02:24:36 +01:00
Author
Owner
Copy Link

@github-actions[bot] commented on GitHub (Jan 25, 2025):

This issue is stale because it has been open for 90 days with no activity.

@github-actions[bot] commented on GitHub (Jan 25, 2025): This issue is stale because it has been open for 90 days with no activity.
adam commented 2025-12-29 02:24:36 +01:00
Author
Owner
Copy Link

@github-actions[bot] commented on GitHub (Feb 1, 2025):

This issue was closed because it has been inactive for 14 days since being marked as stale.

@github-actions[bot] commented on GitHub (Feb 1, 2025): This issue was closed because it has been inactive for 14 days since being marked as stale.
adam commented 2025-12-29 02:24:37 +01:00
Author
Owner
Copy Link

@zalsader commented on GitHub (Jun 19, 2025):

It now also fails with this error:

2025-06-19T00:40:15-04:00 FTL github.com/juanfont/headscale/cmd/headscale/cli/root.go:48 > Error loading config error="Fatal config error: headscale now requires a new `noise.private_key_path` field in the config file for the Tailscale v2 protocol\nFatal config error: server_url must start with https:// or http://"

A workaround is to define those as dummy values in config.yaml:

server_url:  https://example.com
noise:
  private_key_path: /var/lib/headscale/noise_private.key
@zalsader commented on GitHub (Jun 19, 2025): It now also fails with this error: ``` 2025-06-19T00:40:15-04:00 FTL github.com/juanfont/headscale/cmd/headscale/cli/root.go:48 > Error loading config error="Fatal config error: headscale now requires a new `noise.private_key_path` field in the config file for the Tailscale v2 protocol\nFatal config error: server_url must start with https:// or http://" ``` A workaround is to define those as dummy values in `config.yaml`: ``` server_url: https://example.com noise: private_key_path: /var/lib/headscale/noise_private.key ```
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 stale
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#831
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?