{"record":{"id":"637a143bdbb0e9fc","repo":"gastownhall/beads","slug":"server-port-must-be-between-1-and-65535-got-d","errorCode":null,"errorMessage":"--server-port must be between 1 and 65535, got %d; omit the flag to use BEADS_DOLT_SERVER_PORT or the default (%d)","messagePattern":"--server-port must be between 1 and 65535, got (.+?); omit the flag to use BEADS_DOLT_SERVER_PORT or the default \\((.+?)\\)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/bd/init.go","lineNumber":3192,"sourceCode":"// explicitly (--server-host or --server-port) also clears an ambient\n// BEADS_DOLT_SERVER_SOCKET unless --server-socket was itself given. An\n// explicitly empty --server-socket clears the ambient socket too: empty is\n// the documented \"use TCP\" value (see configfile.GetDoltServerSocket).\n// Changed-but-empty host/user and out-of-range port values fail explicitly\n// rather than being silently ignored.\nfunc resolveExplicitServerConnEnv(cmd *cobra.Command) ([]serverConnEnvMutation, error) {\n\tvar muts []serverConnEnvMutation\n\tif cmd.Flags().Changed(\"server-host\") {\n\t\tv, _ := cmd.Flags().GetString(\"server-host\")\n\t\tif v == \"\" {\n\t\t\treturn nil, fmt.Errorf(\"--server-host cannot be empty; omit the flag to use BEADS_DOLT_SERVER_HOST or the default (%s)\", configfile.DefaultDoltServerHost)\n\t\t}\n\t\tmuts = append(muts, serverConnEnvMutation{key: \"BEADS_DOLT_SERVER_HOST\", value: v})\n\t}\n\tif cmd.Flags().Changed(\"server-port\") {\n\t\tv, _ := cmd.Flags().GetInt(\"server-port\")\n\t\tif v < 1 || v > 65535 {\n\t\t\treturn nil, fmt.Errorf(\"--server-port must be between 1 and 65535, got %d; omit the flag to use BEADS_DOLT_SERVER_PORT or the default (%d)\", v, configfile.DefaultDoltServerPort)\n\t\t}\n\t\tmuts = append(muts, serverConnEnvMutation{key: \"BEADS_DOLT_SERVER_PORT\", value: strconv.Itoa(v)})\n\t}\n\tif cmd.Flags().Changed(\"server-user\") {\n\t\tv, _ := cmd.Flags().GetString(\"server-user\")\n\t\tif v == \"\" {\n\t\t\treturn nil, fmt.Errorf(\"--server-user cannot be empty; omit the flag to use BEADS_DOLT_SERVER_USER or the default (%s)\", configfile.DefaultDoltServerUser)\n\t\t}\n\t\tmuts = append(muts, serverConnEnvMutation{key: \"BEADS_DOLT_SERVER_USER\", value: v})\n\t}\n\tswitch {\n\tcase cmd.Flags().Changed(\"server-socket\"):\n\t\tv, _ := cmd.Flags().GetString(\"server-socket\")\n\t\tif v == \"\" {\n\t\t\tmuts = append(muts, serverConnEnvMutation{key: \"BEADS_DOLT_SERVER_SOCKET\", unset: true})\n\t\t} else {\n\t\t\tmuts = append(muts, serverConnEnvMutation{key: \"BEADS_DOLT_SERVER_SOCKET\", value: v})\n\t\t}","sourceCodeStart":3174,"sourceCodeEnd":3210,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/cmd/bd/init.go#L3174-L3210","documentation":"resolveExplicitServerConnEnv validates the --server-port flag range when explicitly provided. Ports below 1 or above 65535 are invalid TCP ports and produce this error, which also hints that omitting the flag falls back to BEADS_DOLT_SERVER_PORT or configfile.DefaultDoltServerPort. The invalid value is echoed in the message via %d.","triggerScenarios":"Running a command that promotes server flags with `--server-port 0`, `--server-port 70000`, a negative number, or a non-numeric value that cobra's GetInt coerced/defaulted oddly.","commonSituations":"Typos like --server-port 655536; shell expansion of an empty/unset variable to 0; copying a host:port pair wholesale into the port flag; range-boundary confusion.","solutions":["Pass a valid port between 1 and 65535","Omit --server-port to use BEADS_DOLT_SERVER_PORT or the default","Fix the variable feeding the flag so it evaluates to a valid port"],"exampleFix":"// before\nbd init --server-port 70000\n// after\nbd init --server-port 3307\n# or omit and use env:\nexport BEADS_DOLT_SERVER_PORT=3307","handlingStrategy":"validation","validationCode":"if ! (( PORT >= 1 && PORT <= 65535 )); then echo \"invalid port: $PORT\" >&2; exit 1; fi","typeGuard":null,"tryCatchPattern":"if err := cmd.Execute(); err != nil && strings.Contains(err.Error(), \"--server-port must be between 1 and 65535\") { /* fix port */ }","preventionTips":["Validate port variables before interpolation into CLI flags","Remember valid TCP ports are 1-65535","Don't paste host:port pairs into the port flag","Use env BEADS_DOLT_SERVER_PORT for defaults instead of computed flags"],"tags":["cli","validation","dolt-server","port"],"backgroundTag":"invalid-port-range","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}