What causes "failed to parse --graphite-url (%s) - %s" in nsqio/nsq?

Print/inspect the exact --graphite-url value (cat -A or %q) to expose hidden control characters, then fix or retype it

failed to parse --graphite-url (%s) - %s

Error message

failed to parse --graphite-url (%s) - %s

What it means

nsqadmin.New validates --graphite-url with url.Parse, but only when --proxy-graphite is enabled (nsqadmin then proxies /render requests to Graphite). url.Parse almost never fails; it only rejects structurally broken URLs, mainly strings containing control characters (0x00-0x1f, 0x7f). This error is a fatal startup error returned from the nsqadmin constructor.

Source

Thrown at nsqadmin/nsqadmin.go:101

	for _, address := range opts.NSQLookupdHTTPAddresses {
		_, err := net.ResolveTCPAddr("tcp", address)
		if err != nil {
			return nil, fmt.Errorf("failed to resolve --lookupd-http-address (%s) - %s", address, err)
		}
	}

	for _, address := range opts.NSQDHTTPAddresses {
		_, err := net.ResolveTCPAddr("tcp", address)
		if err != nil {
			return nil, fmt.Errorf("failed to resolve --nsqd-http-address (%s) - %s", address, err)
		}
	}

	if opts.ProxyGraphite {
		url, err := url.Parse(opts.GraphiteURL)
		if err != nil {
			return nil, fmt.Errorf("failed to parse --graphite-url (%s) - %s", opts.GraphiteURL, err)
		}
		n.graphiteURL = url
	}

	if opts.AllowConfigFromCIDR != "" {
		_, _, err := net.ParseCIDR(opts.AllowConfigFromCIDR)
		if err != nil {
			return nil, fmt.Errorf("failed to parse --allow-config-from-cidr (%s) - %s", opts.AllowConfigFromCIDR, err)
		}
	}

	opts.BasePath = normalizeBasePath(opts.BasePath)

	n.logf(LOG_INFO, version.String("nsqadmin"))

	var err error
	n.httpListener, err = net.Listen("tcp", n.getOpts().HTTPAddress)
	if err != nil {

View on GitHub (pinned to 85cf10c09c)

Solutions

Print/inspect the exact --graphite-url value (cat -A or %q) to expose hidden control characters, then fix or retype it
Use a fully qualified URL such as http://graphite.example.com:80 (scheme + host)
If you do not need Graphite graph proxying in the UI, drop --proxy-graphite so the parse is skipped entirely
Pre-validate the value with url.Parse in your init system / wrapper script before launching nsqadmin

Example fix

# before (env var contains a trailing newline)
--proxy-graphite
--graphite-url=$GRAPHITE_URL   # value: "http://graphite:80\n"

# after (validated, literal value)
--proxy-graphite
--graphite-url=http://graphite.example.com:80

Defensive patterns

Strategy: validation

Validate before calling

if opts.ProxyGraphite {
	if _, err := url.Parse(opts.GraphiteURL); err != nil {
		log.Fatalf("bad --graphite-url %q: %v", opts.GraphiteURL, err)
	}
}

Try / catch

n, err := nsqadmin.New(opts)
if err != nil {
	if strings.Contains(err.Error(), "failed to parse --graphite-url") {
		// config typo: fix the URL and restart; not retryable
	}
	log.Fatal(err)
}

Prevention

Render flag values with %q in logs to expose hidden control characters
Source the URL from a validated secret/config key, not ad-hoc env interpolation
Smoke-test startup in CI with the production flag set

When it happens

Trigger: Starting nsqadmin with --proxy-graphite and a --graphite-url value that contains control characters, raw tabs/newlines, or other characters Go's URL parser refuses (e.g. a value injected from an environment variable or config file with trailing whitespace/newline).

Common situations: Graphite URL sourced from an env var or systemd unit that accidentally embeds a newline; copy/paste of a URL with a stray non-printable character; template interpolation (Ansible/Helm) injecting spaces or quotes; enabling --proxy-graphite without ever validating the URL.

Understand the failure class

Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

AI-assisted analysis of nsqio/nsq@85cf10c09c (2026-08-16). Data as JSON: /api/errors/b35565caf0a43611. Report an issue: GitHub.