SigNoz/signoz · error · errors.SignozError

ErrCodeInvalidGatewayConfig

ErrCodeInvalidGatewayConfig

Error message

url is required

What it means

Returned by the gateway Config.Validate when the URL field is nil — the ingestion-gateway client requires an upstream URL to forward data to. It is a startup-time misconfiguration, not a runtime network error.

Source

Thrown at pkg/gateway/config.go:30

}

func NewConfigFactory() factory.ConfigFactory {
	return factory.NewConfigFactory(factory.MustNewName("gateway"), newConfig)
}

func newConfig() factory.Config {
	return &Config{
		URL: &url.URL{
			Scheme: "http",
			Host:   "localhost:8080",
			Path:   "/",
		},
	}
}

func (c Config) Validate() error {
	if c.URL == nil {
		return errors.New(errors.TypeInvalidInput, ErrCodeInvalidGatewayConfig, "url is required")
	}

	return nil
}

View on GitHub (pinned to 5069bf80b0)

Solutions

1. Set the gateway URL in config: gateway.url / corresponding env var (e.g. http://gateway:8080)
2. If gateway is optional in your topology, skip constructing/validating the gateway config entirely
3. Add a startup check that fails fast with a clear message when the env var is absent

Example fix

// before
cfg := gateway.Config{}
err := cfg.Validate() // url is required

// after
u, _ := url.Parse("http://ingestion-gateway:8080")
cfg := gateway.Config{URL: u}
err := cfg.Validate() // nil

raw := os.Getenv("SIGNOZ_INGESTION_GATEWAY_URL")
if raw == "" {
    return fmt.Errorf("gateway URL env var is required")
}
u, err := url.Parse(raw)
if err != nil { return err }
cfg := gateway.Config{URL: u}
if err := cfg.Validate(); err != nil { return err }

func hasGatewayURL(c gateway.Config) bool { return c.URL != nil }

When it happens

Trigger: Constructing gateway.Config without setting URL (nil *url.URL) and calling Validate; typically when the gateway URL env var (e.g. SIGNOZ_INGESTION_GATEWAY_URL) is unset so unmarshalling leaves URL nil.

Common situations: Deploying without the gateway URL env var set; yaml config missing the url key under gateway:; typos in the env var name; optional-gateway treated as required after an upgrade.

Related errors

• CodeInvalidInput
• CodeInvalidInput
• ErrCodeRoleInvalidInput
• ErrCodeInvalidResolver
• CodeInvalidInput

AI-assisted analysis of SigNoz/signoz@5069bf80b0 (2026-08-28). Data as JSON: /api/errors/6a261e163115ae24. Report an issue: GitHub.