benbjohnson/litestream · error

unknown replica type in config: %q

Error message

unknown replica type in config: %q

What it means

The replica's resolved type (from its URL scheme or `type` field via c.ReplicaType()) does not match any supported backend switch case in NewReplicaFromConfig, so Litestream cannot build a replica client.

Source

Thrown at cmd/litestream/main.go:1412

		}
	case "sftp":
		if r.Client, err = newSFTPReplicaClientFromConfig(c, r); err != nil {
			return nil, err
		}
	case "webdav":
		if r.Client, err = newWebDAVReplicaClientFromConfig(c, r); err != nil {
			return nil, err
		}
	case "nats":
		if r.Client, err = newNATSReplicaClientFromConfig(c, r); err != nil {
			return nil, err
		}
	case "oss":
		if r.Client, err = newOSSReplicaClientFromConfig(c, r); err != nil {
			return nil, err
		}
	default:
		return nil, fmt.Errorf("unknown replica type in config: %q", c.ReplicaType())
	}

	r.Client.SetLogger(r.Logger())

	return r, nil
}

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

	// Parse configPath from URL, if specified.
	configPath := c.Path
	if c.URL != "" {
		if _, _, configPath, err = litestream.ParseReplicaURL(c.URL); err != nil {

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Use a supported URL scheme: s3://, gcs://, abs://, sftp://, file://, oss://
2. Fix the `type:` field spelling to match a supported backend exactly
3. Confirm your Litestream build includes the backend (some replica clients are build-tag gated); rebuild if needed

Example fix

# before
replicas:
  - url: redis://cache/db
# after
replicas:
  - url: s3://bucket/db

allowed := map[string]bool{"s3":true,"gcs":true,"abs":true,"sftp":true,"file":true,"oss":true}
if !allowed[strings.ToLower(cfg.ReplicaType())] {
    return fmt.Errorf("replica type %q not supported", cfg.ReplicaType())
}

When it happens

Trigger: `url: redis://...` or an unknown scheme in the replica config, or a `type:` value that is not one of s3, gcs, abs, sftp, file, oss, etc.

Common situations: Typos like `s4://` or `S3://` with wrong casing depending on normalization; using a backend compiled out of the build (e.g. oss only in CN builds); pointing at a provider via a scheme Litestream doesn't know.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• must specify replica for database
• cannot specify 'replica' and 'replicas' on a database
• multiple replicas on a single database are no longer support
• failed to configure replica for %s: %w
• failed to configure replica %d for %s: %w

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