What causes "ensure bucket %s: %w" in juicedata/juicefs?

Regenerate the Storj access grant and update the configuration (access grants can expire or be revoked).

ensure bucket %s: %w

Error message

ensure bucket %s: %w

What it means

storjClient.Create wraps storj's project.EnsureBucket with retry backoff (storjBackoff); if bucket creation still fails, the error is wrapped as 'ensure bucket <name>'. The %w wrapping preserves the underlying Storj error (auth, project ID, network, quota).

Source

Thrown at pkg/object/storj.go:98

func (s *storjClient) Limits() Limits {
	return Limits{
		IsSupportMultipartUpload: true,
		IsSupportUploadPartCopy:  false,
		MinPartSize:              5 << 20,
		MaxPartSize:              5 << 30,
		MaxPartCount:             10000,
	}
}

func (s *storjClient) Shutdown() {
	_ = s.project.Close()
}

func (s *storjClient) Create(ctx context.Context) error {
	return storjBackoff(ctx, func() error {
		_, err := s.project.EnsureBucket(ctx, s.bucket)
		if err != nil {
			return fmt.Errorf("ensure bucket %s: %w", s.bucket, err)
		}
		return nil
	})
}

func (s *storjClient) Head(ctx context.Context, key string) (Object, error) {
	var object *uplink.Object
	err := storjBackoff(ctx, func() error {
		var e error
		object, e = s.project.StatObject(ctx, s.bucket, key)
		return e
	})
	if err != nil {
		if errors.Is(err, uplink.ErrObjectNotFound) {
			return nil, os.ErrNotExist
		}
		return nil, err
	}

View on GitHub (pinned to c9a67b23e8)

Solutions

Regenerate the Storj access grant and update the configuration (access grants can expire or be revoked).
Verify the satellite address and project match the access grant.
Check bucket-name validity (Storj naming rules) and network reachability to the satellite; retry after transient outages since the call is already backoff-retried.

Defensive patterns

Strategy: try-catch

Validate before calling

// validate access grant before mounting
uplinkCfg := uplink.Config{}
proj, err := uplinkCfg.OpenProject(ctx, accessGrant)
if err != nil { return fmt.Errorf("invalid storj access grant: %v", err) }

Try / catch

if err := store.Create(ctx); err != nil {
    var se *uplink.Error
    if errors.As(err, &se) {
        log.Printf("storj ensure bucket failed: class=%v cause=%v", se.Class, se.Details)
    }
    return err
}

Prevention

Test the access grant with uplink CLI before configuring JuiceFS.
Regenerate access grants on rotation schedules.
Confirm satellite address and project match the grant.

When it happens

Trigger: Calling Create on a storj object store when EnsureBucket fails: invalid access grant/API key, wrong satellite address, nonexistent project, bucket name violating Storj rules, or persistent network failure beyond the backoff budget.

Common situations: Expired or revoked Storj access grant in JuiceFS config; misconfigured satellite URL; project ID mismatch between the access grant and configured endpoint.

Understand the failure class

Background: "API request failed": what wrapped HTTP errors from external APIs mean and how to find the real cause — this error's family across 29 libraries.

Related errors

AI-assisted analysis of juicedata/juicefs@c9a67b23e8 (2026-09-06). Data as JSON: /api/errors/aa96b9c2f1a6354f. Report an issue: GitHub.