{"record":{"id":"68bad3620971baa3","repo":"henrygd/beszel","slug":"no-key-provided-must-set-key-flag-key-env-var","errorCode":null,"errorMessage":"no key provided: must set -key flag, KEY env var, or KEY_FILE env var. Use 'beszel-agent help' for usage","messagePattern":"no key provided: must set -key flag, KEY env var, or KEY_FILE env var\\. Use 'beszel-agent help' for usage","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/cmd/agent/agent.go","lineNumber":127,"sourceCode":"\treturn false\n}\n\n// loadPublicKeys loads the public keys from the command line flag, environment variable, or key file.\nfunc (opts *cmdOptions) loadPublicKeys() ([]ssh.PublicKey, error) {\n\t// Try command line flag first\n\tif opts.key != \"\" {\n\t\treturn agent.ParseKeys(opts.key)\n\t}\n\n\t// Try environment variable\n\tif key, ok := utils.GetEnv(\"KEY\"); ok && key != \"\" {\n\t\treturn agent.ParseKeys(key)\n\t}\n\n\t// Try key file\n\tkeyFile, ok := utils.GetEnv(\"KEY_FILE\")\n\tif !ok {\n\t\treturn nil, fmt.Errorf(\"no key provided: must set -key flag, KEY env var, or KEY_FILE env var. Use 'beszel-agent help' for usage\")\n\t}\n\n\tpubKey, err := os.ReadFile(keyFile)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to read key file: %w\", err)\n\t}\n\treturn agent.ParseKeys(string(pubKey))\n}\n\nfunc (opts *cmdOptions) getAddress() string {\n\treturn agent.GetAddress(opts.listen)\n}\n\n// handleFingerprint handles the \"fingerprint\" command with subcommands \"view\" and \"reset\".\nfunc handleFingerprint() {\n\tsubCmd := \"\"\n\tif len(os.Args) > 2 {\n\t\tsubCmd = os.Args[2]","sourceCodeStart":109,"sourceCodeEnd":145,"githubUrl":"https://github.com/henrygd/beszel/blob/b38fb7dafa60812cc22e6a84ce313e94f1ce0a32/internal/cmd/agent/agent.go#L109-L145","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Set the KEY environment variable to the public key shown in the hub admin UI when adding the system.","Or pass the key via the -key flag at launch.","Or write the public key to a file and set KEY_FILE=/path/to/keyfile (good for secret mounts).","In Docker add `- KEY=<pubkey>` to environment and recreate the container; in systemd add Environment=KEY=... and daemon-reload."],"exampleFix":"# before\nservices:\n  beszel-agent:\n    image: henrygd/beszel-agent\n# after\nservices:\n  beszel-agent:\n    image: henrygd/beszel-agent\n    environment:\n      - KEY=ssh-ed25519 AAAA...  # paste hub public key","handlingStrategy":"validation","validationCode":"// fail fast with a clear message before starting the agent\nif os.Getenv(\"KEY\") == \"\" && keyFlag == \"\" && os.Getenv(\"KEY_FILE\") == \"\" {\n\tlog.Fatal(\"beszel-agent: no key provided; set -key, KEY, or KEY_FILE\")\n}","typeGuard":null,"tryCatchPattern":"keys, err := loadPublicKeys(opts)\nif err != nil {\n\tif strings.HasPrefix(err.Error(), \"no key provided\") {\n\t\tlog.Fatalf(\"%v — see hub UI to copy the public key\", err)\n\t}\n\tlog.Fatal(err)\n}","preventionTips":["Always set KEY (or KEY_FILE) in compose/systemd unit templates.","Copy the key directly from the hub admin UI when adding a system.","Smoke-test agent startup after config changes.","Document the required env var in deployment docs."],"tags":["go","configuration","ssh","missing-env-var"],"backgroundTag":"missing-env-var","analyzedSha":"b38fb7dafa60812cc22e6a84ce313e94f1ce0a32","analyzedAt":"2026-08-31T15:10:10.149Z","schemaVersion":2},"datasetVersion":"2026-08-31T19:17:28.585Z"}