{"record":{"id":"ba6c77f49e543401","repo":"juicedata/juicefs","slug":"object-storage-s","errorCode":null,"errorMessage":"object storage: %s","messagePattern":"object storage: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"cmd/mount.go","lineNumber":617,"sourceCode":"\t}\n\t// stage 0: check the connection to fail fast\n\t// stage 2: need the volume name to check if it's already mounted\n\t// stage 3: the real service process\n\tif stage != 1 {\n\t\tmetaCli = meta.NewClient(addr, metaConf)\n\t\tformat, err = metaCli.Load(true)\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\t}\n\n\tchunkConf := getChunkConf(c, format)\n\tvfsConf := getVfsConf(c, metaConf, format, chunkConf)\n\tsetFuseOption(c, format, vfsConf)\n\tif stage == 0 || stage == 3 {\n\t\tblob, err = NewReloadableStorage(format, metaCli, updateFormat(c))\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"object storage: %s\", err)\n\t\t}\n\t\tlogger.Infof(\"Data use %s\", blob)\n\n\t}\n\n\tif stage < 3 {\n\t\t// supervisor serves no user request\n\t\tif metaCli != nil {\n\t\t\tif err = metaCli.Shutdown(); err != nil {\n\t\t\t\tlogger.Errorf(\"[pid=%d] meta shutdown: %s\", os.Getpid(), err)\n\t\t\t}\n\t\t}\n\t\tif blob != nil {\n\t\t\t// test storage at startup to fail fast instead of throwing EIO in the middle of user's workload\n\t\t\tif c.Bool(\"check-storage\") {\n\t\t\t\tstart := time.Now()\n\t\t\t\tif err = test(context.Background(), blob); err != nil {\n\t\t\t\t\tlogger.Errorf(\"Object storage test failed: %s\", err)","sourceCodeStart":599,"sourceCodeEnd":635,"githubUrl":"https://github.com/juicedata/juicefs/blob/c9a67b23e8e08ec23ec331aa6f1675e2319e921c/cmd/mount.go#L599-L635","documentation":"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>`.","triggerScenarios":"`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.","commonSituations":"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.","solutions":["Run `juicefs status META-URL` and check the format's Storage/Bucket fields are correct and the storage type is supported","If overriding on CLI, validate --storage and --bucket values (correct enum name, valid URL); remove overrides and test with the stored format","Ensure object-store credentials are present in the environment (ACCESS_KEY/SECRET_KEY or provider config, e.g. AWS/GCP) before mounting","Test bucket reachability with the object store CLI (aws s3 ls / mc ls) using the same credentials/endpoint","Re-format is not required — fix the format via the storage settings or re-create the volume config if Storage is fundamentally wrong"],"exampleFix":"// before\n$ juicefs mount --storage s3 --bucket \"not-a-url\" redis://localhost /mnt/jfs\n  -> object storage: invalid bucket\n// after\n$ juicefs mount --storage s3 --bucket \"https://mybucket.s3.us-east-1.amazonaws.com\" redis://localhost /mnt/jfs","handlingStrategy":"validation","validationCode":"// validate object storage settings before mounting\nfmt, err := metaCli.Load(true)\nif err != nil { return err }\nif _, ok := objectStorages[fmt.Storage]; !ok {\n    return fmt.Errorf(\"unsupported storage type %q\", fmt.Storage)\n}\nu, err := url.Parse(fmt.Bucket)\nif err != nil || u.Host == \"\" && !strings.HasPrefix(fmt.Bucket, \"/\") {\n    return fmt.Errorf(\"invalid bucket %q\", fmt.Bucket)\n}\n// and ensure credentials exist\nif os.Getenv(\"ACCESS_KEY\") == \"\" && os.Getenv(\"SECRET_KEY\") == \"\" {\n    // rely on provider chain; warn otherwise\n}","typeGuard":"// Go: guard the storage type before constructing the backend\nfunc storageSupported(t string) bool {\n    _, ok := objectStorages[t]\n    return ok\n}","tryCatchPattern":"// mount CLI returns the error to the caller; handle at top level\nif err := mount(c); err != nil {\n    if strings.HasPrefix(err.Error(), \"object storage:\") {\n        logger.Fatalf(\"check --storage/--bucket and credentials: %v\", err)\n    }\n    return err\n}","preventionTips":["Validate --storage against the supported list before mounting","Use fully qualified, reachable bucket URLs including region/endpoint","Keep object-store credentials in the mount process environment or a provider chain","After credential rotation, re-run `juicefs status` and remount rather than relying on stale clients","Test the bucket with aws-cli/mc using identical settings before mounting"],"tags":["object-storage","mount","configuration","s3"],"backgroundTag":"invalid-config-value","analyzedSha":"c9a67b23e8e08ec23ec331aa6f1675e2319e921c","analyzedAt":"2026-09-06T17:55:48.476Z","contentChangedAt":"2026-09-06T17:55:48.476Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}