What causes "unable to open storage connection" in kopia/kopia?

Check the wrapped cause for the actual blob.NewStorage failure (auth, network, throttling).

unable to open storage connection

Error message

unable to open storage connection

What it means

kopia's provider validation failed to create one of the additional blob.Storage connections to the same backend. The underlying blob.NewStorage error is wrapped as 'unable to open storage connection', and kopia first attempts to close already-opened connections, logging any close failure as a warning.

Solutions

Check the wrapped cause for the actual blob.NewStorage failure (auth, network, throttling).
Verify provider credentials and endpoint in the connection info.
Reduce opt.NumEquivalentStorageConnections if the provider throttles concurrent connections.
Re-run validation; also clear KOPIA_SKIP_PROVIDER_VALIDATION only when validation is intended to run.

Example fix

// before
opt := &providervalidation.Options{NumEquivalentStorageConnections: 10}
// after
opt := &providervalidation.Options{NumEquivalentStorageConnections: 2}

Defensive patterns

Strategy: retry

Validate before calling

// validate connection info before opening duplicates
if err := ci.Validate(); err != nil {
    return fmt.Errorf("invalid connection info: %w", err)
}

Try / catch

err := providervalidation.ValidateProvider(ctx, st, opts)
var retryable = isNetworkErr(err)
if retryable {
    time.Sleep(backoff)
    err = providervalidation.ValidateProvider(ctx, st, opts)
}

Prevention

Verify blob provider credentials and endpoint before validation
Reduce NumEquivalentStorageConnections on throttling providers
Ensure network/DNS reachability of the blob endpoint from the host
Pre-flight the first connection before requesting duplicates

When it happens

Trigger: blob.NewStorage(ctx, ci, false) returns an error while opening connection i (1..n-1) in openEquivalentStorageConnections — invalid connection info, bad credentials, unreachable endpoint, or too many parallel connections for the provider.

Common situations: Azure/S3 credentials valid for the first connection but throttled afterwards; transient DNS/network failure; misbuilt connection info for the duplicate connections.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

AI-assisted analysis of kopia/kopia@82495e54b5 (2026-09-07). Data as JSON: /api/errors/9cd8bf74224bae9f. Report an issue: GitHub.

Appendix: source

Thrown at internal/providervalidation/providervalidation.go:90

	return errors.Wrap(err, "error closing additional connections")
}

// openEquivalentStorageConnections creates n-1 additional connections to the same underlying storage
// and returns a slice of all connections.
func openEquivalentStorageConnections(ctx context.Context, st blob.Storage, n int) (equivalentBlobStorageConnections, error) {
	result := equivalentBlobStorageConnections{st}
	ci := st.ConnectionInfo()

	log(ctx).Infof("Opening %v equivalent storage connections...", n-1)

	for i := 1; i < n; i++ {
		c, err := blob.NewStorage(ctx, ci, false)
		if err != nil {
			if cerr := result.closeAdditional(ctx); cerr != nil {
				log(ctx).Warn("unable to close storage connection", "err", cerr)
			}

			return nil, errors.Wrap(err, "unable to open storage connection")
		}

		log(ctx).Debugw("opened equivalent storage connection", "connectionID", i)

		result = append(result, loggingwrapper.NewWrapper(c, log(ctx), nil, fmt.Sprintf("[STORAGE-%v] ", i)))
	}

	return result, nil
}

// ValidateProvider runs a series of tests against provided storage to validate that
// it can be used with Kopia.
//
//nolint:mnd,funlen,gocyclo,cyclop
func ValidateProvider(ctx context.Context, st0 blob.Storage, opt Options) error {
	if os.Getenv("KOPIA_SKIP_PROVIDER_VALIDATION") != "" {
		return nil
	}

View on GitHub (pinned to 82495e54b5)