juicedata/juicefs · error

please create bucket %s manually

Error message

please create bucket %s manually

What it means

oos.Create() probes the bucket by issuing a List request; if that probe returns any error it reports that the OOS bucket does not exist and cannot be auto-created. The OOS storage driver has no CreateBucket capability, so the user must provision the bucket out-of-band (OOS is compatible with S3 APIs, so any S3 tool works). Note the returned error is generic and swallows the underlying probe error.

Source

Thrown at pkg/object/oos.go:56

}

func (s *oos) String() string {
	return fmt.Sprintf("oos://%s/", s.s3client.bucket)
}

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

func (s *oos) Create(ctx context.Context) error {
	_, _, _, err := s.List(ctx, "", "", "", "", 1, true)
	if err != nil {
		return fmt.Errorf("please create bucket %s manually", s.s3client.bucket)
	}
	return err
}

func (s *oos) List(ctx context.Context, prefix, start, token, delimiter string, limit int64, followLink bool) ([]Object, bool, string, error) {
	if limit > 1000 {
		limit = 1000
	}
	objs, hasMore, nextMarker, err := s.s3client.List(ctx, prefix, start, token, delimiter, limit, followLink)
	if start != "" && len(objs) > 0 && objs[0].Key() == start {
		objs = objs[1:]
	}
	return objs, hasMore, nextMarker, err
}

func newOOS(endpoint, accessKey, secretKey, token string) (ObjectStorage, error) {
	if !strings.Contains(endpoint, "://") {
		endpoint = fmt.Sprintf("https://%s", endpoint)

View on GitHub (pinned to c9a67b23e8)

Solutions

1. Create the bucket manually in the OOS console or via an S3-compatible CLI/tool with the exact name configured.
2. Verify access key/secret key and endpoint are correct and the credentials have ListBucket permission (the probe List error is hidden, so test with an S3 client).
3. Check network reachability to the OOS endpoint from the client host.

Example fix

// before
_, _, _, err := s.List(ctx, "", "", "", "", 1, true)
if err != nil {
    return fmt.Errorf("please create bucket %s manually", s.s3client.bucket)
}
// after (surface the cause)
_, _, _, err := s.List(ctx, "", "", "", "", 1, true)
if err != nil {
    return fmt.Errorf("please create bucket %s manually (probe failed: %w)", s.s3client.bucket, err)
}

_, err := s3Client.HeadBucket(&s3.HeadBucketInput{Bucket: aws.String(bucket)})
if err != nil {
    return fmt.Errorf("bucket %q does not exist or is not accessible: create it first", bucket)
}

if err := store.Create(ctx); err != nil {
    if strings.Contains(err.Error(), "please create bucket") {
        // verify bucket name/credentials, then create bucket via OOS console or s3 tool
    }
    return err
}

When it happens

Trigger: Calling Create on an oos ObjectStorage whose bucket was never created in the OOS console/API, or when the probe List fails for any reason (bad credentials, wrong endpoint, network error, no permission) — the message is returned for all of these because the underlying error is discarded.

Common situations: Fresh JuiceFS volume setup pointing at a not-yet-created OOS bucket; typo in bucket name; access key lacking ListBucket permission; wrong region/endpoint configured so the List call fails and is misreported as 'bucket missing'.

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

• Failed to create bucket %s: %s, previous error: %s Please cr
• ceph: can't put empty file
• GOOGLE_CLOUD_PROJECT environment variable must be set
• object key cannot be empty
• not exists

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