kopia/kopia · error

error listing blobs

Error message

error listing blobs

What it means

`ensureEmpty` lists blobs in the target storage before creating a repository, aborting early if any blob exists. When `ListBlobs` itself fails (other than the internal sentinel meaning 'data found'), the error is wrapped as 'error listing blobs'. It signals that Kopia could not verify the bucket/container is empty, typically due to a storage backend connectivity, credentials, or permissions problem — not that data exists.

Solutions

1. Verify the storage location (bucket/container) exists and the name is spelled correctly in the provider flags.
2. Test credentials and network access with the provider's CLI (e.g. `aws s3 ls s3://bucket`) using the same account/profile.
3. Check IAM/storage permissions include list operations on the bucket/container.
4. If the location is intentionally non-empty and stale, empty it or choose another location — but first fix the list error itself, since 'found existing data' is reported separately.

Example fix

// before (failing flags)
kopia repository create s3 --bucket=my-bukket --access-key=AKIA... --secret=...
// after (corrected bucket + verified credentials)
kopia repository create s3 --bucket=my-bucket --region=us-east-1 --access-key=AKIA... --secret=...

// Before creating, verify the storage location is reachable and listable.
st, err := f.Connect(ctx, true, formatVersion)
if err != nil { return err }
err := st.ListBlobs(ctx, "", func(md blob.Metadata) error { return nil })
if err != nil {
	return fmt.Errorf("storage not usable (check bucket name, credentials, network): %w", err)
}

if err := c.ensureEmpty(ctx, st); err != nil {
	if strings.Contains(err.Error(), "error listing blobs") {
		// backend access problem: inspect unwrapped cause
		log.Fatalf("storage backend unreachable: %v", errors.Unwrap(err))
	}
	return err
}

When it happens

Trigger: Calling `kopia repository create <provider> ...` where the underlying `blob.Storage.ListBlobs(ctx, "", ...)` call returns a non-nil error (excluding the hasData sentinel). Causes include invalid bucket/container name, missing or expired credentials, no network access to the storage endpoint, or insufficient list permissions (e.g. s3:ListBucket denied).

Common situations: Wrong AWS/GCS/Azure credentials or profiles; nonexistent or misspelled bucket names; IAM policies without ListObjects permission; corporate proxies or offline environments; endpoint misconfiguration for S3-compatible providers (MinIO, B2, rclone).

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• can't connect to storage
• cannot initialize repository
• error comparing directories
• error copying data
• error listing blobs

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

Appendix: source

Thrown at cli/command_repository_create.go:113

		RetentionMode:                     blob.RetentionMode(c.retentionMode),
		RetentionPeriod:                   c.retentionPeriod,
		FormatBlockKeyDerivationAlgorithm: c.createBlockKeyDerivationAlgorithm,
	}
}

func (c *commandRepositoryCreate) ensureEmpty(ctx context.Context, s blob.Storage) error {
	hasDataError := errors.New("has data")

	err := s.ListBlobs(ctx, "", func(_ blob.Metadata) error {
		return hasDataError
	})

	if errors.Is(err, hasDataError) {
		return errors.New("found existing data in storage location")
	}

	return errors.Wrap(err, "error listing blobs")
}

func (c *commandRepositoryCreate) runCreateCommandWithStorage(ctx context.Context, st blob.Storage) error {
	err := c.ensureEmpty(ctx, st)
	if err != nil {
		return errors.Wrap(err, "unable to get repository storage")
	}

	options := c.newRepositoryOptionsFromFlags()

	pass, err := c.svc.getPasswordFromFlags(ctx, true, false)
	if err != nil {
		return errors.Wrap(err, "getting password")
	}

	log(ctx).Info("Initializing repository with:")

	if options.BlockFormat.Version != 0 {

View on GitHub (pinned to 82495e54b5)