MHSanaei/3x-ui · error

XUI_PORT must be between 1 and 65535

Error message

XUI_PORT must be between 1 and 65535

What it means

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.

Source

Thrown at internal/config/config.go:123

}

// IsSkipHSTS returns true if skipping HSTS mode is enabled via the XUI_SKIP_HSTS environment variable.
func IsSkipHSTS() bool {
	return os.Getenv("XUI_SKIP_HSTS") == "true"
}

func GetPortOverride() (port int, configured bool, err error) {
	value, ok := os.LookupEnv("XUI_PORT")
	if !ok || strings.TrimSpace(value) == "" {
		return 0, false, nil
	}

	port, err = strconv.Atoi(strings.TrimSpace(value))
	if err != nil {
		return 0, true, fmt.Errorf("parse XUI_PORT: %w", err)
	}
	if port < 1 || port > 65535 {
		return 0, true, fmt.Errorf("XUI_PORT must be between 1 and 65535")
	}

	return port, true, nil
}

// GetBinFolderPath returns the path to the binary folder, defaulting to "bin" if not set via XUI_BIN_FOLDER.
func GetBinFolderPath() string {
	binFolderPath := os.Getenv("XUI_BIN_FOLDER")
	if binFolderPath == "" {
		binFolderPath = "bin"
	}
	return binFolderPath
}

func getBaseDir() string {
	exePath, err := os.Executable()
	if err != nil {
		return "."

View on GitHub (pinned to ad32144c42)

Solutions

1. Choose a port in 1-65535, e.g. XUI_PORT=2053.
2. To get default behavior, unset XUI_PORT so the DB-stored setting applies.
3. Reserve values below 1024 only if the process runs privileged or has CAP_NET_BIND_SERVICE.

Example fix

# before
export XUI_PORT=80800
# after
export XUI_PORT=8080

port, err := strconv.Atoi(strings.TrimSpace(os.Getenv("XUI_PORT")))
if err == nil && (port < 1 || port > 65535) {
    return fmt.Errorf("XUI_PORT=%d out of range 1-65535", port)
}

func bindablePort(v string) (int, bool) {
    n, err := strconv.Atoi(strings.TrimSpace(v))
    if err != nil || n < 1 || n > 65535 {
        return 0, false
    }
    return n, true
}

When it happens

Trigger: 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.

Common situations: Operators using 0 expecting auto-assignment; typos adding a digit; confusing container port with host port and pasting something out of range.

Related errors

• parse XUI_PORT: %w
• XUI_DB_TYPE=postgres but XUI_DB_DSN is empty
• The new username and password are empty
• ❌ Failed to get inbounds.
• tg_id must be a positive integer

AI-assisted analysis of MHSanaei/3x-ui@ad32144c42 (2026-08-15). Data as JSON: /api/errors/dd7314d7a0d1010c. Report an issue: GitHub.