{"record":{"id":"dd7314d7a0d1010c","repo":"MHSanaei/3x-ui","slug":"xui-port-must-be-between-1-and-65535","errorCode":null,"errorMessage":"XUI_PORT must be between 1 and 65535","messagePattern":"XUI_PORT must be between 1 and 65535","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/config/config.go","lineNumber":123,"sourceCode":"}\n\n// IsSkipHSTS returns true if skipping HSTS mode is enabled via the XUI_SKIP_HSTS environment variable.\nfunc IsSkipHSTS() bool {\n\treturn os.Getenv(\"XUI_SKIP_HSTS\") == \"true\"\n}\n\nfunc GetPortOverride() (port int, configured bool, err error) {\n\tvalue, ok := os.LookupEnv(\"XUI_PORT\")\n\tif !ok || strings.TrimSpace(value) == \"\" {\n\t\treturn 0, false, nil\n\t}\n\n\tport, err = strconv.Atoi(strings.TrimSpace(value))\n\tif err != nil {\n\t\treturn 0, true, fmt.Errorf(\"parse XUI_PORT: %w\", err)\n\t}\n\tif port < 1 || port > 65535 {\n\t\treturn 0, true, fmt.Errorf(\"XUI_PORT must be between 1 and 65535\")\n\t}\n\n\treturn port, true, nil\n}\n\n// GetBinFolderPath returns the path to the binary folder, defaulting to \"bin\" if not set via XUI_BIN_FOLDER.\nfunc GetBinFolderPath() string {\n\tbinFolderPath := os.Getenv(\"XUI_BIN_FOLDER\")\n\tif binFolderPath == \"\" {\n\t\tbinFolderPath = \"bin\"\n\t}\n\treturn binFolderPath\n}\n\nfunc getBaseDir() string {\n\texePath, err := os.Executable()\n\tif err != nil {\n\t\treturn \".\"","sourceCodeStart":105,"sourceCodeEnd":141,"githubUrl":"https://github.com/MHSanaei/3x-ui/blob/ad32144c42455696ea9f14e12168beac3e25f5d2/internal/config/config.go#L105-L141","documentation":"GetPortOverride validates the numeric XUI_PORT against the TCP port range and returns this error for anything below 1 or above 65535. The value parsed fine as an integer but is not a bindable port (0, negatives, 65536+). Startup port selection fails until the value is corrected.","triggerScenarios":"XUI_PORT=0 (often meant as 'random' or 'unset' but explicitly rejects), XUI_PORT=80800 (typo), XUI_PORT=-1, or a value copied from a port range end like 65536.","commonSituations":"Operators using 0 expecting auto-assignment; typos adding a digit; confusing container port with host port and pasting something out of range.","solutions":["Choose a port in 1-65535, e.g. XUI_PORT=2053.","To get default behavior, unset XUI_PORT so the DB-stored setting applies.","Reserve values below 1024 only if the process runs privileged or has CAP_NET_BIND_SERVICE."],"exampleFix":"# before\nexport XUI_PORT=80800\n# after\nexport XUI_PORT=8080","handlingStrategy":"validation","validationCode":"port, err := strconv.Atoi(strings.TrimSpace(os.Getenv(\"XUI_PORT\")))\nif err == nil && (port < 1 || port > 65535) {\n    return fmt.Errorf(\"XUI_PORT=%d out of range 1-65535\", port)\n}","typeGuard":"func bindablePort(v string) (int, bool) {\n    n, err := strconv.Atoi(strings.TrimSpace(v))\n    if err != nil || n < 1 || n > 65535 {\n        return 0, false\n    }\n    return n, true\n}","tryCatchPattern":null,"preventionTips":["Do not use 0 to mean 'default' — unset the variable instead.","Double-check host vs container port mappings when copying values into XUI_PORT."],"tags":["config","environment","validation","startup"],"backgroundTag":null,"analyzedSha":"ad32144c42455696ea9f14e12168beac3e25f5d2","analyzedAt":"2026-08-15T11:13:23.905Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}