nats-io/nats-server · error

invalid proxy URL: %v

Error message

invalid proxy URL: %v

What it means

validateLeafNodeProxyOptions parses the remote leaf node's proxy URL with net/url.Parse and wraps any parse failure as "invalid proxy URL: %v". The proxy setting is used to dial remote leaf nodes through an HTTP(S) proxy, so the value must be a syntactically valid URL. Thrown from validateLeafNode and parseRemoteLeafNodes.

Source

Thrown at server/leafnode.go:400

	for _, u := range o.LeafNode.Users {
		if _, exists := users[u.Username]; exists {
			return fmt.Errorf("duplicate user %q detected in leafnode authorization", u.Username)
		}
		users[u.Username] = struct{}{}
	}
	return nil
}

func validateLeafNodeProxyOptions(remote *RemoteLeafOpts) ([]string, error) {
	var warnings []string

	if remote.Proxy.URL == _EMPTY_ {
		return warnings, nil
	}

	proxyURL, err := url.Parse(remote.Proxy.URL)
	if err != nil {
		return warnings, fmt.Errorf("invalid proxy URL: %v", err)
	}

	if proxyURL.Scheme != "http" && proxyURL.Scheme != "https" {
		return warnings, fmt.Errorf("proxy URL scheme must be http or https, got: %s", proxyURL.Scheme)
	}

	if proxyURL.Host == _EMPTY_ {
		return warnings, fmt.Errorf("proxy URL must specify a host")
	}

	if remote.Proxy.Timeout < 0 {
		return warnings, fmt.Errorf("proxy timeout must be >= 0")
	}

	if (remote.Proxy.Username == _EMPTY_) != (remote.Proxy.Password == _EMPTY_) {
		return warnings, fmt.Errorf("proxy username and password must both be specified or both be empty")
	}

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Read the wrapped %v parse error to see the exact syntax problem
2. Provide a fully-qualified URL with scheme and host, e.g. "http://proxy.corp:3128"
3. URL-encode or remove special characters (spaces, raw non-ASCII) in the value

Example fix

// before
proxy { url: "proxy.corp:3128 proxy2" }
// after
proxy { url: "http://proxy.corp:3128" }

if p := cfg.LeafNodes.Proxy.URL; p != "" {
  if _, err := url.Parse(p); err != nil {
    return fmt.Errorf("invalid proxy URL %q: %v", p, err)
  }
}

When it happens

Trigger: A remote leafnode block sets proxy { url: "..." } with a string net/url.Parse cannot parse — e.g. missing scheme with stray characters, invalid percent-escapes, or control characters; raised during option validation or leafnode config parsing.

Common situations: Typing `proxy url: 127.0.0.1:3128` (no scheme) combined with characters url.Parse rejects, or pasting URLs with spaces/newlines from documentation or environment variables.

Understand the failure class

Background: "Invalid URL" / "URL cannot be empty": fix the malformed or missing URL behind request-construction failures — this error's family across 50 libraries.

Related errors

• proxy URL scheme must be http or https, got: %s
• remote leaf node URL %q cannot be used in FIPS-140 mode when
• leaf nodes and gateways (both being defined) require a syste
• leafnode: %v
• invalid leafnode's minimum version: %v

AI-assisted analysis of nats-io/nats-server@3a66a489d2 (2026-09-02). Data as JSON: /api/errors/7dd9f04cf5efa7cc. Report an issue: GitHub.