{"record":{"id":"cbd9c640ec8ca228","repo":"juicedata/juicefs","slug":"new-session-s","errorCode":null,"errorMessage":"new session: %s","messagePattern":"new session: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/object.go","lineNumber":529,"sourceCode":"\t}\n\tmetaConf := meta.DefaultConf()\n\tmetaConf.MaxDeletes = 10\n\tmetaConf.NoBGJob = true\n\tmetaCli := meta.NewClient(metaUrl, metaConf)\n\tformat, err := metaCli.Load(true)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"load setting: %s\", err)\n\t}\n\tblob, err := NewReloadableStorage(format, metaCli, nil)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"object storage: %s\", err)\n\t}\n\tchunkConf := getDefaultChunkConf(format)\n\tstore := chunk.NewCachedStore(blob, *chunkConf, nil)\n\tregisterMetaMsg(metaCli, store, chunkConf)\n\terr = metaCli.NewSession(false)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"new session: %s\", err)\n\t}\n\tmetaCli.OnReload(func(fmt *meta.Format) {\n\t\tstore.UpdateLimit(fmt.UploadLimit, fmt.DownloadLimit)\n\t})\n\n\tvfsConf := &vfs.Config{\n\t\tMeta:            metaConf,\n\t\tFormat:          *format,\n\t\tVersion:         version.Version(),\n\t\tChunk:           chunkConf,\n\t\tAttrTimeout:     time.Second,\n\t\tDirEntryTimeout: time.Second,\n\t\tMountpoint:      cliCtx.String(\"mountpoint\"),\n\t}\n\n\tvfsConf.Format.RemoveSecret()\n\td, _ := json.MarshalIndent(vfsConf, \"  \", \"\")\n\tlogger.Debugf(\"Config: %s\", string(d))","sourceCodeStart":511,"sourceCodeEnd":547,"githubUrl":"https://github.com/juicedata/juicefs/blob/c9a67b23e8e08ec23ec331aa6f1675e2319e921c/cmd/object.go#L511-L547","documentation":"This error wraps the failure of metaCli.NewSession(false) when registering a JuiceFS volume as an object storage backend ('jfs' scheme) in the S3 gateway/sync path. A metadata session is the client's registered, heartbeat-maintained connection to the metadata engine (Redis/SQL/KV); NewSession fails when the engine is unreachable, credentials are wrong, the volume was formatted with a different secret, or the client version is too old for the engine. The underlying engine error is appended to the message, so read the '%s' suffix for the real cause.","triggerScenarios":"Calling object storage APIs against a jfs:// URL (e.g. juicefs sync or gateway with jfs source), which invokes newJFS; metaCli.NewSession returns an error because the metadata URL is bad, the engine is down, authentication fails (wrong --token / password), the volume was deleted, or MinClientVersion checks reject the client.","commonSituations":"Metadata engine (Redis/MySQL/TiKV) not running or network blocked; wrong metadata URL or password after a rotation; volume deleted while a job still references it; older JuiceFS binary talking to a volume created by a newer version; token mismatch for a token-protected volume.","solutions":["Read the wrapped '%s' suffix for the underlying engine error and fix that cause (connectivity, credentials, URL).","Verify the metadata URL is reachable, e.g. redis-cli ping or connecting to the DB with the same credentials.","Re-check the volume still exists: ./juicefs status <meta-url>.","If auth/token related, supply the correct token or remove the password from the URL after rotation.","Upgrade the JuiceFS client if the engine requires a newer MinClientVersion."],"exampleFix":"// before: failing because the metadata engine is unreachable\njuicefs sync jfs://myjfs/ s3://backup/   // new session: dial tcp 10.0.0.5:6379: connect: connection refused\n// after: ensure the engine is up and the URL is correct\n./juicefs status redis://10.0.0.5:6379/1  # verify first, then rerun sync","handlingStrategy":"try-catch","validationCode":"// before using a jfs:// object storage URL, verify the engine is reachable\nif err := exec.Command(\"juicefs\", \"status\", metaURL).Run(); err != nil {\n    return fmt.Errorf(\"metadata engine not reachable for %s: %w\", metaURL, err)\n}","typeGuard":null,"tryCatchPattern":"_, err := object.CreateStorage(\"jfs\", \"myjfs\", \"\", \"\")\nif err != nil {\n    if strings.Contains(err.Error(), \"new session:\") {\n        // inspect wrapped cause, check engine connectivity/credentials, optionally retry\n    }\n    return err\n}","preventionTips":["Pre-flight `juicefs status <meta-url>` in deploy scripts before any jfs:// usage.","Keep metadata engine endpoints, passwords, and tokens in sync with the volume's current secret.","Pin and uniformly upgrade client versions across jobs hitting the same volume.","Alert on metadata engine availability (Redis SENTINEL/MySQL health checks)."],"tags":["metadata","session","redis","storage"],"backgroundTag":"connection-refused","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"}