caddyserver/caddy · error

invalid host in address: %v

Error message

invalid host in address: %v

What it means

NetWriter.Provision runs the configured address through the replacer with ReplaceOrErr(..., true, true) before parsing; this error means a placeholder in the address (e.g. {$SYSLOG_URL}) was either unrecognized or evaluated to empty, so the address cannot be trusted for dialing.

Source

Thrown at modules/logging/netwriter.go:64

	SoftStart bool `json:"soft_start,omitempty"`

	addr caddy.NetworkAddress
}

// CaddyModule returns the Caddy module information.
func (NetWriter) CaddyModule() caddy.ModuleInfo {
	return caddy.ModuleInfo{
		ID:  "caddy.logging.writers.net",
		New: func() caddy.Module { return new(NetWriter) },
	}
}

// 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
}

View on GitHub (pinned to 50e54ee279)

Solutions

1. Export/define the environment variable or placeholder referenced in the net address
2. Replace the placeholder with a literal address to confirm the rest of the config works
3. For systemd deployments, add the variable under [Service] Environment= or EnvironmentFile=

Example fix

# before
output net {$SYSLOG_HOST}:514 {
} # SYSLOG_HOST unset

# after
# export SYSLOG_HOST=log.internal before starting caddy, or:
output net log.internal:514

if os.Getenv("SYSLOG_HOST") == "" {
    return fmt.Errorf("SYSLOG_HOST must be set for net output address")
}

if err := nw.Provision(ctx); err != nil {
    if strings.Contains(err.Error(), "invalid host in address") {
        // a placeholder was unset/unknown: fix environment and reload
    }
    return err
}

When it happens

Trigger: Configuring output net with an address containing a placeholder that is undefined at provisioning time, such as 'net {$LOG_HOST}:514}' when the environment variable is unset.

Common situations: Env-var placeholders not exported in the service unit; typos in placeholder names; running config in a context (different user, container) where the variable is absent.

Related errors

• parsing network address '%s': %v
• multiple ports not supported
• timeout cannot be less than 0
• replacing listen address: %v
• download failed: %v

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