benbjohnson/litestream · error

bucket required for gs replica

Error message

bucket required for gs replica

What it means

Required-field guard in newGSReplicaClientFromConfig: after applying URL parts and explicit config fields, no GCS bucket was resolved for the replica, so a client cannot be constructed. Fires when neither the 'url' host nor the 'bucket' config field supplies a bucket name.

Source

Thrown at cmd/litestream/main.go:1747

	// Apply settings from URL, if specified.
	if c.URL != "" {
		_, uhost, upath, err := litestream.ParseReplicaURL(c.URL)
		if err != nil {
			return nil, err
		}

		// Only apply URL parts to field that have not been overridden.
		if configPath == "" {
			configPath = upath
		}
		if bucket == "" {
			bucket = uhost
		}
	}

	// Ensure required settings are set.
	if bucket == "" {
		return nil, fmt.Errorf("bucket required for gs replica")
	}

	// Build replica.
	client := gs.NewReplicaClient()
	client.Bucket = bucket
	client.Path = configPath
	return client, nil
}

// newABSReplicaClientFromConfig returns a new instance of abs.ReplicaClient built from config.
func newABSReplicaClientFromConfig(c *ReplicaConfig, _ *litestream.Replica) (_ *abs.ReplicaClient, err error) {
	// Ensure URL & constituent parts are not both specified.
	if c.URL != "" && c.Path != "" {
		return nil, fmt.Errorf("cannot specify url & path for abs replica")
	} else if c.URL != "" && c.Bucket != "" {
		return nil, fmt.Errorf("cannot specify url & bucket for abs replica")
	}

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Set bucket in config or use a gs://bucket/path url

When it happens

Trigger: Thrown at cmd/litestream/main.go:1747 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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