{"record":{"id":"54fbe6f86d4eb7ef","repo":"juicedata/juicefs","slug":"new-hdfs-client-s-s","errorCode":null,"errorMessage":"new HDFS client %s: %s","messagePattern":"new HDFS client (.+?): (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/object/hdfs.go","lineNumber":334,"sourceCode":"\t\t\treturn nil, fmt.Errorf(\"Problem with kerberos authentication: %s\", err)\n\t\t}\n\t} else {\n\t\tif username == \"\" {\n\t\t\tusername = os.Getenv(\"HADOOP_USER_NAME\")\n\t\t}\n\t\tif username == \"\" {\n\t\t\tcurrent, err := user.Current()\n\t\t\tif err != nil {\n\t\t\t\treturn nil, fmt.Errorf(\"get current user: %s\", err)\n\t\t\t}\n\t\t\tusername = current.Username\n\t\t}\n\t\toptions.User = username\n\t}\n\n\tc, err := hdfs.NewClient(options)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"new HDFS client %s: %s\", rpcAddr, err)\n\t}\n\tif os.Getenv(\"HADOOP_SUPER_USER\") != \"\" {\n\t\tsuperuser = os.Getenv(\"HADOOP_SUPER_USER\")\n\t}\n\tif os.Getenv(\"HADOOP_SUPER_GROUP\") != \"\" {\n\t\tsupergroup = os.Getenv(\"HADOOP_SUPER_GROUP\")\n\t}\n\n\tvar replication = 3\n\tif v, found := conf[\"dfs.replication\"]; found {\n\t\tif x, err := strconv.Atoi(v); err == nil {\n\t\t\treplication = x\n\t\t}\n\t}\n\tvar umask uint16 = 022\n\tif v, found := conf[\"fs.permissions.umask-mode\"]; found {\n\t\tif x, err := strconv.ParseUint(v, 8, 16); err == nil {\n\t\t\tumask = uint16(x)","sourceCodeStart":316,"sourceCodeEnd":352,"githubUrl":"https://github.com/juicedata/juicefs/blob/c9a67b23e8e08ec23ec331aa6f1675e2319e921c/pkg/object/hdfs.go#L316-L352","documentation":"newHDFS finalizes by calling hdfs.NewClient(options) to establish the RPC connection to the NameNode. If the client cannot be constructed — unreachable NameNode, bad addresses, protocol/ negotiation failure — the error is wrapped as \"new HDFS client %s: %s\" with the resolved RPC addresses. Client object creation succeeded up to this point; this is a connectivity or cluster-level failure.","triggerScenarios":"newHDFS called when the NameNode host:port from the hdfs:// addr / core-site.xml (fs.defaultFS) is unreachable, DNS fails, the cluster is down, or client options (user, kerberos) are rejected during connection setup.","commonSituations":"NameNode in safe mode or down; firewall blocking RPC port 8020/9000; wrong fs.defaultFS; hostname resolution failure inside containers; version incompatibility between client and cluster.","solutions":["Check the wrapped inner error and test connectivity to the RPC address: nc -vz namenode 8020 (or the printed rpcAddr).","Verify fs.defaultFS in core-site.xml and the hdfs:// address match the actual NameNode and port.","Confirm the NameNode is up and out of safe mode (hdfs dfsadmin -safemode get).","Fix DNS/hostname resolution (add entries to /etc/hosts) if the error is a lookup failure."],"exampleFix":"// before\n$ ./juicefs mount hdfs://nn:9000/data /mnt/jfs\nnew HDFS client nn:9000: dial tcp: lookup nn: no such host\n// after\n$ grep fs.defaultFS $HADOOP_CONF_DIR/core-site.xml   # confirm host/port\n$ echo \"10.0.0.5 nn\" | sudo tee -a /etc/hosts\n$ ./juicefs mount hdfs://nn:9000/data /mnt/jfs","handlingStrategy":"retry","validationCode":"host, port := \"namenode\", 8020\nconn, err := net.DialTimeout(\"tcp\", net.JoinHostPort(host, port), 3*time.Second)\nif err != nil {\n    return fmt.Errorf(\"NameNode %s unreachable: %w\", net.JoinHostPort(host, port), err)\n}\nconn.Close()","typeGuard":null,"tryCatchPattern":"os, err := object.CreateStorage(\"hdfs\", addr, \"\", \"\")\nif err != nil && strings.Contains(err.Error(), \"new HDFS client\") {\n    // transient NameNode unavailability: retry with backoff\n    for i := 0; i < 5; i++ {\n        time.Sleep(time.Duration(1<<i) * time.Second)\n        if os, err = object.CreateStorage(\"hdfs\", addr, \"\", \"\"); err == nil {\n            break\n        }\n    }\n}","preventionTips":["Health-check the NameNode RPC port before mounting.","Pin correct hostnames in /etc/hosts or DNS inside containers.","Monitor NameNode safe-mode and availability.","Verify fs.defaultFS matches the address you pass."],"tags":["hdfs","network","connection","object-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-14T05:17:10.506Z"}