juicedata/juicefs · error

missing URL

Error message

missing URL

What it means

NewBridge constructs a metrics Bridge (for the Java SDK's libjfs monitoring) that pushes Prometheus metrics to a push gateway. It returns "missing URL" when the supplied Config.URL is the empty string, because without a gateway URL there is nowhere to push metrics.

Source

Thrown at sdk/java/libjfs/bridge.go:116

	g            prometheus.Gatherer
	commonLabels map[string]string
}

// Logger is the minimal interface Bridge needs for logging. Note that
// log.Logger from the standard library implements this interface, and it is
// easy to implement by custom loggers, if they don't do so already anyway.
type Logger interface {
	Println(v ...interface{})
}

// NewBridge returns a pointer to a new Bridge struct.
func NewBridge(c *Config) (*Bridge, error) {
	b := &Bridge{}

	b.useTags = c.UseTags

	if c.URL == "" {
		return nil, errors.New("missing URL")
	}
	b.url = c.URL

	if c.Gatherer == nil {
		b.g = prometheus.DefaultGatherer
	} else {
		b.g = c.Gatherer
	}

	if c.Logger != nil {
		b.logger = c.Logger
	}

	if c.Prefix != "" {
		b.prefix = c.Prefix
	}

	var z time.Duration

View on GitHub (pinned to c9a67b23e8)

Solutions

1. Set Config.URL to the full push gateway address (e.g. http://host:9091/metrics/job/juicefs) before calling NewBridge.
2. Validate the URL in the Java layer before entering the bridge so the failure surfaces earlier.
3. Check the env/config source that feeds the URL for unset or empty values.

Example fix

// before
b, err := NewBridge(&Config{UseTags: true})
// after
b, err := NewBridge(&Config{UseTags: true, URL: "http://pushgateway:9091/metrics/job/jfs"})

if cfg.URL == "" {
	return fmt.Errorf("push gateway URL must be set (Config.URL)")
}
_, err := url.ParseRequestURI(cfg.URL)
if err != nil {
	return fmt.Errorf("invalid push gateway URL %q: %w", cfg.URL, err)
}

b, err := NewBridge(cfg)
if err != nil {
	log.Fatalf("metrics bridge init failed: %v", err)
}

When it happens

Trigger: Calling NewBridge with a *Config whose URL field was never set (zero-value Config), or set to "" after skipping validation; callers such as push2Graphite/TestPush construct configs dynamically and an unset variable ends up as the URL.

Common situations: Java-side configuration omits the push gateway address, an environment variable feeding the URL is unset, or a refactored constructor path stopped copying the URL field into the Config struct.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• missing URL
• name is required
• JuiceFS initialized failed for jfs://" + name
• wrong ranger config: %s
• illegal value for parameter 'ranger-rest-url': " + url

AI-assisted analysis of juicedata/juicefs@c9a67b23e8 (2026-09-06). Data as JSON: /api/errors/9a6196dfe3d7678b. Report an issue: GitHub.