henrygd/beszel · error

no key provided: must set -key flag, KEY env var, or KEY_FIL

Error message

no key provided: must set -key flag, KEY env var, or KEY_FILE env var. Use 'beszel-agent help' for usage

What it means

loadPublicKeys resolves the agent's SSH public key(s) from the -key flag, KEY env var, or KEY_FILE env var, in that order. If none is set, it returns this descriptive error listing every supported source, because the agent cannot authenticate clients without at least one public key.

Source

Thrown at internal/cmd/agent/agent.go:127

	return false
}

// loadPublicKeys loads the public keys from the command line flag, environment variable, or key file.
func (opts *cmdOptions) loadPublicKeys() ([]ssh.PublicKey, error) {
	// Try command line flag first
	if opts.key != "" {
		return agent.ParseKeys(opts.key)
	}

	// Try environment variable
	if key, ok := utils.GetEnv("KEY"); ok && key != "" {
		return agent.ParseKeys(key)
	}

	// Try key file
	keyFile, ok := utils.GetEnv("KEY_FILE")
	if !ok {
		return nil, fmt.Errorf("no key provided: must set -key flag, KEY env var, or KEY_FILE env var. Use 'beszel-agent help' for usage")
	}

	pubKey, err := os.ReadFile(keyFile)
	if err != nil {
		return nil, fmt.Errorf("failed to read key file: %w", err)
	}
	return agent.ParseKeys(string(pubKey))
}

func (opts *cmdOptions) getAddress() string {
	return agent.GetAddress(opts.listen)
}

// handleFingerprint handles the "fingerprint" command with subcommands "view" and "reset".
func handleFingerprint() {
	subCmd := ""
	if len(os.Args) > 2 {
		subCmd = os.Args[2]

View on GitHub (pinned to b38fb7dafa)

Solutions

1. Set the KEY environment variable to the public key shown in the hub admin UI when adding the system.
2. Or pass the key via the -key flag at launch.
3. Or write the public key to a file and set KEY_FILE=/path/to/keyfile (good for secret mounts).
4. In Docker add `- KEY=<pubkey>` to environment and recreate the container; in systemd add Environment=KEY=... and daemon-reload.

Example fix

# before
services:
  beszel-agent:
    image: henrygd/beszel-agent
# after
services:
  beszel-agent:
    image: henrygd/beszel-agent
    environment:
      - KEY=ssh-ed25519 AAAA...  # paste hub public key

// fail fast with a clear message before starting the agent
if os.Getenv("KEY") == "" && keyFlag == "" && os.Getenv("KEY_FILE") == "" {
	log.Fatal("beszel-agent: no key provided; set -key, KEY, or KEY_FILE")
}

keys, err := loadPublicKeys(opts)
if err != nil {
	if strings.HasPrefix(err.Error(), "no key provided") {
		log.Fatalf("%v — see hub UI to copy the public key", err)
	}
	log.Fatal(err)
}

When it happens

Trigger: Starting beszel-agent with no -key flag, no KEY env var, and no KEY_FILE env var — typically a first run where the hub's generated public key was never provided to the agent.

Common situations: Docker/systemd deployments missing the KEY env entry; agent started manually without flags; compose env entries lost after an update; user assumed the agent fetches the key from the hub automatically.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• failed to read key file: %w
• SSH disabled
• ${resp.Error}
• timeout creating session
• HUB_URL environment variable not set

AI-assisted analysis of henrygd/beszel@b38fb7dafa (2026-08-31). Data as JSON: /api/errors/68bad3620971baa3. Report an issue: GitHub.