kopia/kopia · error

can't connect to storage

Error message

can't connect to storage

What it means

`kopia repository repair` connects to the underlying blob storage (via the provided storage flags) before attempting recovery, using f.Connect(ctx, false, 0). If the storage backend cannot be reached or authenticated, the connection error is wrapped with "can't connect to storage". This is a pre-repository-layer failure: the raw blob storage itself is inaccessible.

Solutions

1. Read the wrapped cause (errors.Cause) to see the provider-specific failure (auth, DNS, not-found).
2. Verify all storage connection flags (endpoint, bucket/container, credentials) with `kopia repository repair --help` and re-run.
3. Test connectivity independently, e.g. `kopia repository create s3 --dry-run` or aws/gcloud CLI listing the bucket.
4. Fix/refresh credentials (env vars, ~/.kopia credentials, cloud IAM) and retry the repair command.

Example fix

// before
st, err := f.Connect(ctx, false, 0)
if err != nil {
	return errors.Wrap(err, "can't connect to storage")
}
// after
st, err := f.Connect(ctx, false, 0)
if err != nil {
	return errors.Wrap(err, "can't connect to storage") // check flags: kopia repository repair --file-system-path=...
}

// Go: preflight connectivity before running repair
ctx, cancel := context.WithTimeout(ctx, 30*time.Second)
defer cancel()
if _, err := f.Connect(ctx, false, 0); err != nil {
	return fmt.Errorf("storage unreachable, fix flags/credentials before repair: %w", err)
}

// Go: nil-check the returned storage before use
st, err := f.Connect(ctx, false, 0)
if err != nil || st == nil {
	return errors.Wrap(err, "can't connect to storage")
}

st, err := f.Connect(ctx, false, 0)
if err != nil {
	return errors.Wrap(err, "can't connect to storage") // surface errors.Cause to the user with flag guidance
}

When it happens

Trigger: Running `kopia repository repair` with incorrect/missing storage credentials or endpoint flags, network outage to the blob store, wrong bucket/container name, or a provider returning auth errors so f.Connect cannot establish a storage session.

Common situations: Typo in --s3-bucket/--s3-endpoint or filesystem path during disaster recovery; expired cloud credentials (S3 keys, GCS/Azure tokens); DNS or firewall blocking the storage endpoint; repairing after the provider region changed.

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

• cannot initialize repository
• cannot open storage
• error comparing directories
• error copying data
• error listing blobs

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

Appendix: source

Thrown at cli/command_repository_repair.go:38

func (c *commandRepositoryRepair) setup(svc advancedAppServices, parent commandParent) {
	cmd := parent.Command("repair", "DEPRECATED: Recover format blob from older-format packs.").Hidden()

	cmd.Flag("recover-format", "Recover format blob from a copy").Default("auto").EnumVar(&c.repairCommandRecoverFormatBlob, "auto", "yes", "no")
	cmd.Flag("recover-format-block-prefixes", "Prefixes of file names").StringsVar(&c.repairCommandRecoverFormatBlobPrefixes)
	cmd.Flag("dry-run", "Do not modify repository").Short('n').BoolVar(&c.repairDryRun)

	for _, prov := range svc.storageProviders() {
		f := prov.NewFlags()
		cc := cmd.Command(prov.Name, "Repair repository in "+prov.Description).Hidden()
		f.Setup(svc, cc)
		cc.Action(func(kpc *kingpin.ParseContext) error {
			svc.dangerousCommand()

			return svc.runAppWithContext(kpc.SelectedCommand, func(ctx context.Context) error {
				st, err := f.Connect(ctx, false, 0)
				if err != nil {
					return errors.Wrap(err, "can't connect to storage")
				}

				return c.runRepairCommandWithStorage(ctx, st)
			})
		})
	}
}

func packBlockPrefixes() []string {
	var str []string

	for _, p := range content.PackBlobIDPrefixes {
		str = append(str, string(p))
	}

	return str
}

View on GitHub (pinned to 82495e54b5)