What causes "timeout cannot be less than 0" in caddyserver/caddy?

Set dial_timeout to a positive duration like 10s, or remove it to use the default

timeout cannot be less than 0

Error message

timeout cannot be less than 0

What it means

NetWriter.Provision validates that the optional dial_timeout is non-negative. A negative duration in JSON (or Caddyfile) has no meaningful semantics for a dialer and is rejected at provisioning.

Source

Thrown at modules/logging/netwriter.go:77

// Provision sets up the module.
func (nw *NetWriter) Provision(ctx caddy.Context) error {
	repl := caddy.NewReplacer()
	address, err := repl.ReplaceOrErr(nw.Address, true, true)
	if err != nil {
		return fmt.Errorf("invalid host in address: %v", err)
	}

	nw.addr, err = caddy.ParseNetworkAddress(address)
	if err != nil {
		return fmt.Errorf("parsing network address '%s': %v", address, err)
	}

	if nw.addr.PortRangeSize() != 1 {
		return fmt.Errorf("multiple ports not supported")
	}

	if nw.DialTimeout < 0 {
		return fmt.Errorf("timeout cannot be less than 0")
	}

	return nil
}

func (nw NetWriter) String() string {
	return nw.addr.String()
}

// WriterKey returns a unique key representing this nw.
func (nw NetWriter) WriterKey() string {
	return nw.addr.String()
}

// OpenWriter opens a new network connection.
func (nw NetWriter) OpenWriter() (io.WriteCloser, error) {
	reconn := &redialerConn{
		nw:      nw,

View on GitHub (pinned to 50e54ee279)

Solutions

Set dial_timeout to a positive duration like 10s, or remove it to use the default
Use 0 (or omit) rather than a negative value to express 'default'

Example fix

// before
{"output": {"output": "net", "address": "udp/h:514", "dial_timeout": "-5s"}}

// after
{"output": {"output": "net", "address": "udp/h:514", "dial_timeout": "10s"}}

Defensive patterns

Strategy: validation

Validate before calling

if d, err := time.ParseDuration(cfg.DialTimeout); err == nil && d < 0 {
    return fmt.Errorf("dial_timeout must be >= 0")
}

Prevention

Use positive durations or omit dial_timeout for the default
Template guards: clamp computed timeouts to 0 minimum

When it happens

Trigger: Setting dial_timeout to a negative value in the net writer config, e.g. {"dial_timeout": "-5s"} or 'dial_timeout -5s' in Caddyfile syntax.

Common situations: Sign typos in duration strings; templates subtracting from a timeout and going below zero; confusing a '0 means default' convention with negative sentinels.

Understand the failure class

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

Related errors

AI-assisted analysis of caddyserver/caddy@50e54ee279 (2026-08-15). Data as JSON: /api/errors/76d4377edd3add2f. Report an issue: GitHub.