What causes "opentelemetry: batch timeout must be greater than 0" in weaviate/weaviate?

Set BatchTimeout to a positive duration, e.g. 5 * time.Second.

opentelemetry: batch timeout must be greater than 0

Error message

opentelemetry: batch timeout must be greater than 0

What it means

ErrInvalidBatchTimeout is returned by the OpenTelemetry config's IsValid() when Config.BatchTimeout is zero or negative (config.go:132). The batch timeout controls how long the batch span/metric processor waits before flushing; a non-positive value would either never flush or immediately spin, so it is rejected.

Source

Thrown at usecases/telemetry/opentelemetry/errors.go:27

//  CONTACT: hello@weaviate.io
//

package opentelemetry

import "errors"

var (
	// ErrEmptyServiceName is returned when the service name is empty
	ErrEmptyServiceName = errors.New("opentelemetry: service name cannot be empty")

	// ErrEmptyExporterEndpoint is returned when the exporter endpoint is empty
	ErrEmptyExporterEndpoint = errors.New("opentelemetry: exporter endpoint cannot be empty")

	// ErrInvalidSamplingRate is returned when the sampling rate is invalid
	ErrInvalidSamplingRate = errors.New("opentelemetry: sampling rate must be between 0.0 and 1.0")

	// ErrInvalidBatchTimeout is returned when the batch timeout is invalid
	ErrInvalidBatchTimeout = errors.New("opentelemetry: batch timeout must be greater than 0")

	// ErrInvalidBatchSize is returned when the batch size is invalid
	ErrInvalidBatchSize = errors.New("opentelemetry: batch size must be greater than 0")

	// ErrExporterNotSupported is returned when the exporter protocol is not supported
	ErrExporterNotSupported = errors.New("opentelemetry: exporter protocol not supported")
)

View on GitHub (pinned to 75aa4b6d11)

Solutions

Set BatchTimeout to a positive duration, e.g. 5 * time.Second.
Check duration parsing of env/config values — a failed parse yields the zero value and triggers this error.
Rely on the library default if you do not need custom batching.

Example fix

// before
cfg := opentelemetry.Config{ServiceName: "weaviate", ExporterEndpoint: "otel:4317", BatchTimeout: 0}
// after
cfg := opentelemetry.Config{ServiceName: "weaviate", ExporterEndpoint: "otel:4317", BatchTimeout: 5 * time.Second}

Defensive patterns

Strategy: validation

Validate before calling

if cfg.BatchTimeout <= 0 {
	return fmt.Errorf("batch timeout must be > 0, got %v", cfg.BatchTimeout)
}

Try / catch

if err := cfg.IsValid(); err != nil {
	if errors.Is(err, opentelemetry.ErrInvalidBatchTimeout) {
		cfg.BatchTimeout = 5 * time.Second
	}
}

Prevention

Include time units when parsing duration env vars (use time.ParseDuration).
Guard against zero-value Config structs by validating before use.
Use library defaults when you don't need custom batch timings.
Log the parsed duration at startup to confirm the unit conversion.

When it happens

Trigger: Setting the batch timeout to 0 or a negative duration in the OpenTelemetry configuration, e.g. parsing a duration string that failed and silently produced 0.

Common situations: Zero-value Config structs where the timeout field was never set; duration env vars parsed incorrectly (missing time unit); templates defaulting the field to 0.

Understand the failure class

Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

AI-assisted analysis of weaviate/weaviate@75aa4b6d11 (2026-09-04). Data as JSON: /api/errors/fd19196204bf6bd7. Report an issue: GitHub.