juicedata/juicefs · critical

object storage: %s

Error message

object storage: %s

What it means

Wraps the error from NewReloadableStorage(format, metaCli, updateFormat(c)) during `juicefs mount` — the step that builds the object-storage (blob) client from the volume format stored in the metadata engine. NewReloadableStorage parses the format's Storage type/ Bucket settings and constructs the corresponding backend (s3, oss, minio, ...); any failure constructing or validating that backend (unsupported storage type, invalid endpoint URL, missing credentials) is reported as `object storage: <err>`.

Source

Thrown at cmd/mount.go:617

	}
	// stage 0: check the connection to fail fast
	// stage 2: need the volume name to check if it's already mounted
	// stage 3: the real service process
	if stage != 1 {
		metaCli = meta.NewClient(addr, metaConf)
		format, err = metaCli.Load(true)
		if err != nil {
			return err
		}
	}

	chunkConf := getChunkConf(c, format)
	vfsConf := getVfsConf(c, metaConf, format, chunkConf)
	setFuseOption(c, format, vfsConf)
	if stage == 0 || stage == 3 {
		blob, err = NewReloadableStorage(format, metaCli, updateFormat(c))
		if err != nil {
			return fmt.Errorf("object storage: %s", err)
		}
		logger.Infof("Data use %s", blob)

	}

	if stage < 3 {
		// supervisor serves no user request
		if metaCli != nil {
			if err = metaCli.Shutdown(); err != nil {
				logger.Errorf("[pid=%d] meta shutdown: %s", os.Getpid(), err)
			}
		}
		if blob != nil {
			// test storage at startup to fail fast instead of throwing EIO in the middle of user's workload
			if c.Bool("check-storage") {
				start := time.Now()
				if err = test(context.Background(), blob); err != nil {
					logger.Errorf("Object storage test failed: %s", err)

View on GitHub (pinned to c9a67b23e8)

Solutions

1. Run `juicefs status META-URL` and check the format's Storage/Bucket fields are correct and the storage type is supported
2. If overriding on CLI, validate --storage and --bucket values (correct enum name, valid URL); remove overrides and test with the stored format
3. Ensure object-store credentials are present in the environment (ACCESS_KEY/SECRET_KEY or provider config, e.g. AWS/GCP) before mounting
4. Test bucket reachability with the object store CLI (aws s3 ls / mc ls) using the same credentials/endpoint
5. Re-format is not required — fix the format via the storage settings or re-create the volume config if Storage is fundamentally wrong

Example fix

// before
$ juicefs mount --storage s3 --bucket "not-a-url" redis://localhost /mnt/jfs
  -> object storage: invalid bucket
// after
$ juicefs mount --storage s3 --bucket "https://mybucket.s3.us-east-1.amazonaws.com" redis://localhost /mnt/jfs

// validate object storage settings before mounting
fmt, err := metaCli.Load(true)
if err != nil { return err }
if _, ok := objectStorages[fmt.Storage]; !ok {
    return fmt.Errorf("unsupported storage type %q", fmt.Storage)
}
u, err := url.Parse(fmt.Bucket)
if err != nil || u.Host == "" && !strings.HasPrefix(fmt.Bucket, "/") {
    return fmt.Errorf("invalid bucket %q", fmt.Bucket)
}
// and ensure credentials exist
if os.Getenv("ACCESS_KEY") == "" && os.Getenv("SECRET_KEY") == "" {
    // rely on provider chain; warn otherwise
}

// Go: guard the storage type before constructing the backend
func storageSupported(t string) bool {
    _, ok := objectStorages[t]
    return ok
}

// mount CLI returns the error to the caller; handle at top level
if err := mount(c); err != nil {
    if strings.HasPrefix(err.Error(), "object storage:") {
        logger.Fatalf("check --storage/--bucket and credentials: %v", err)
    }
    return err
}

When it happens

Trigger: `juicefs mount META-URL MOUNTPOINT` where the volume format references an object store that cannot be initialized: unknown/corrupted format.Storage value, malformed Bucket URL, missing AccessKey/SecretKey env vars, unsupported scheme, or --storage/--bucket overrides on the CLI that produce an invalid configuration.

Common situations: Typo in --storage type flag; --bucket pointing at an unreachable/invalid endpoint; rotating object-store credentials and the new env vars aren't set in the mount environment; format was edited (updateFormat) with an unsupported storage combination; region mismatch making the S3 client constructor fail.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• Failed to put: %s
• Failed to create bucket %s: %s, previous error: %s Please cr
• Failed to create bucket %s: %s, previous error: %s
• Failed to get: %s
• read wrong data: expected %x, got %x

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