What causes "webdav-url required for webdav replica" in benbjohnson/litestream?

Add 'webdav-url: https:// ' to the webdav replica config

webdav-url required for webdav replica

Error message

webdav-url required for webdav replica

What it means

newWebDAVReplicaClientFromConfig requires the WebDAV server endpoint. If neither 'webdav-url' nor a URL with a usable host component yielded a non-empty webdavURL, the client cannot reach any server and this error is returned at startup.

Source

Thrown at cmd/litestream/main.go:1899

		if webdavURL == "" && u.Host != "" {
			webdavURL = fmt.Sprintf("%s://%s", scheme, u.Host)
		}

		// Extract credentials from URL
		if username == "" && u.User != nil {
			username = u.User.Username()
		}
		if password == "" && u.User != nil {
			password, _ = u.User.Password()
		}
		if path == "" {
			path = u.Path
		}
	}

	// Ensure required settings are set.
	if webdavURL == "" {
		return nil, fmt.Errorf("webdav-url required for webdav replica")
	}

	// Build replica.
	client := webdav.NewReplicaClient()
	client.URL = webdavURL
	client.Username = username
	client.Password = password
	client.Path = path

	return client, nil
}

// newNATSReplicaClientFromConfig returns a new instance of nats.ReplicaClient built from config.
func newNATSReplicaClientFromConfig(c *ReplicaConfig, _ *litestream.Replica) (_ *nats.ReplicaClient, err error) {
	// Parse URL if provided to extract bucket name and server URL
	var url, bucket string
	if c.URL != "" {
		scheme, host, bucketPath, err := litestream.ParseReplicaURL(c.URL)

View on GitHub (pinned to 4ed7a308f6)

Solutions

Add 'webdav-url: https://<dav-server>' to the webdav replica config
Or provide a complete URL with host: 'url: webdavs://dav.example.com/db'
Check env expansion: ensure the variable holding the server address is set in the litestream process environment

Example fix

# before
- type: webdav
  username: backup
  password: secret
  path: /db
# after
- type: webdav
  webdav-url: https://dav.example.com
  username: backup
  password: secret
  path: /db

Defensive patterns

Strategy: validation

Validate before calling

if rep.Type == "webdav" {
    endpoint := rep.WebDAVURL
    if endpoint == "" && rep.URL != "" {
        if u, err := url.Parse(rep.URL); err == nil && u.Host != "" { endpoint = u.Scheme + "://" + u.Host }
    }
    if endpoint == "" { return fmt.Errorf("webdav replica %s: missing webdav-url", rep.Name) }
}

Prevention

Always set webdav-url (or a url with host) for webdav replicas
Verify env-expanded values are non-empty at startup
Test-parse the URL scheme (webdav/webdavs) before deploying

When it happens

Trigger: A webdav replica with no 'webdav-url' and a 'url' whose host part is empty (e.g. 'webdav:///db' or a bare 'webdav://'), so webdavURL stays empty after URL application.

Common situations: Config assembled from env vars where the server address variable was empty; typo'd scheme like 'webdav:db' with no authority component; partially filled webdav block with only credentials.

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

AI-assisted analysis of benbjohnson/litestream@4ed7a308f6 (2026-09-06). Data as JSON: /api/errors/f93822413e53d053. Report an issue: GitHub.