{"record":{"id":"5ac8b0839a6483d4","repo":"henrygd/beszel","slug":"hub-url-environment-variable-not-set","errorCode":null,"errorMessage":"HUB_URL environment variable not set","messagePattern":"HUB_URL environment variable not set","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"agent/client.go","lineNumber":50,"sourceCode":"type WebSocketClient struct {\n\tgws.BuiltinEventHandler\n\toptions            *gws.ClientOption                   // WebSocket client configuration options\n\tagent              *Agent                              // Reference to the parent agent\n\tConn               *gws.Conn                           // Active WebSocket connection\n\thubURL             *url.URL                            // Parsed hub URL for connection\n\ttoken              string                              // Authentication token for hub registration\n\tfingerprint        string                              // System fingerprint for identification\n\thubRequest         *common.HubRequest[cbor.RawMessage] // Reusable request structure for message parsing\n\tlastConnectAttempt time.Time                           // Timestamp of last connection attempt\n\thubVerified        bool                                // Whether the hub has been cryptographically verified\n}\n\n// newWebSocketClient creates a new WebSocket client for the given agent.\n// It reads configuration from environment variables and validates the hub URL.\nfunc newWebSocketClient(agent *Agent) (client *WebSocketClient, err error) {\n\thubURLStr, exists := utils.GetEnv(\"HUB_URL\")\n\tif !exists {\n\t\treturn nil, errors.New(\"HUB_URL environment variable not set\")\n\t}\n\n\tclient = &WebSocketClient{}\n\n\tclient.hubURL, err = url.Parse(hubURLStr)\n\tif err != nil || client.hubURL.Host == \"\" {\n\t\treturn nil, fmt.Errorf(\"invalid HUB_URL %q: must include scheme and host (e.g. http://hub.example.com:8090)\", hubURLStr)\n\t}\n\t// get registration token\n\tclient.token, err = getToken()\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\tclient.agent = agent\n\tclient.hubRequest = &common.HubRequest[cbor.RawMessage]{}\n\tclient.fingerprint = agent.getFingerprint()\n","sourceCodeStart":32,"sourceCodeEnd":68,"githubUrl":"https://github.com/henrygd/beszel/blob/b38fb7dafa60812cc22e6a84ce313e94f1ce0a32/agent/client.go#L32-L68","documentation":"newWebSocketClient reads the hub endpoint from the HUB_URL environment variable before constructing the WebSocketClient. If HUB_URL is unset (utils.GetEnv returns exists=false), the client cannot know where to connect and throws this error immediately, before any URL parsing or connection attempt.","triggerScenarios":"The agent is started (Start or newWebSocketClient directly) without HUB_URL exported in the process environment; also triggered by the listed tests when the variable is not seeded.","commonSituations":"Deploying via systemd/Docker/Kubernetes without passing the env var; running the agent binary from a shell where only TOKEN is set; typo like HUBURL or HUB_UR; config file not sourced before launch.","solutions":["Set the environment variable, e.g. export HUB_URL=wss://hub.example.com, before starting the agent.","If running under systemd, add Environment=HUB_URL=... to the unit file; for Docker use -e HUB_URL=... or an env_file.","Check for typos in the variable name and that it is set in the same process/user that runs the agent.","Fail fast at startup: validate required env vars before launching the service."],"exampleFix":"// before\n./agent   # TOKEN set but HUB_URL missing -> error\n// after\nexport HUB_URL=\"wss://hub.example.com\"\nexport TOKEN=\"...\"\n./agent","handlingStrategy":"validation","validationCode":"if hubURL, ok := os.LookupEnv(\"HUB_URL\"); !ok || hubURL == \"\" {\n\treturn fmt.Errorf(\"HUB_URL must be set (e.g. wss://hub.example.com)\")\n}","typeGuard":null,"tryCatchPattern":"client, err := newWebSocketClient(agent)\nif err != nil {\n\tif strings.Contains(err.Error(), \"HUB_URL\") {\n\t\tlog.Fatal(\"startup config incomplete: set HUB_URL, e.g. HUB_URL=wss://hub.example.com\")\n\t}\n\tlog.Fatal(err)\n}","preventionTips":["Validate all required env vars (HUB_URL, TOKEN/TOKEN_FILE) at process startup with fail-fast.","Use an env-file or secret manager so the variable ships with every deployment.","Add a startup smoke test in CI that runs the agent with expected env config.","Watch out for typos: HUB_URL vs HUBURL vs HUB_URl."],"tags":["configuration","environment","websocket","startup"],"backgroundTag":"missing-env-var","analyzedSha":"b38fb7dafa60812cc22e6a84ce313e94f1ce0a32","analyzedAt":"2026-08-31T15:10:10.149Z","schemaVersion":2},"datasetVersion":"2026-08-31T19:17:28.585Z"}