{"record":{"id":"0ec4ede49975fb29","repo":"databendlabs/databend","slug":"name-node-is-required-for-storage-hdfs","errorCode":null,"errorMessage":"name_node is required for storage hdfs","messagePattern":"name_node is required for storage hdfs","errorType":"validation","errorClass":"InvalidInput","httpStatus":null,"severity":"error","filePath":"src/query/sql/src/planner/binder/location.rs","lineNumber":389,"sourceCode":"\n    let name_node = match (name_node_option, name_node_from_uri) {\n        (Some(n1), Some(n2)) => {\n            if n1 != &n2 {\n                return Err(Error::new(\n                    ErrorKind::InvalidInput,\n                    format!(\n                        \"name_node in uri({n2}) and from connection option 'name_node'({n1}) not match.\"\n                    ),\n                ));\n            } else {\n                n2\n            }\n        }\n        (Some(n1), None) => n1.to_string(),\n        (None, Some(n2)) => n2,\n        (None, None) => {\n            // we prefer user to specify name_node in options\n            return Err(Error::new(\n                ErrorKind::InvalidInput,\n                \"name_node is required for storage hdfs\",\n            ));\n        }\n    };\n    let sp = StorageParams::Hdfs(databend_common_meta_app::storage::StorageHdfsConfig {\n        name_node,\n        root,\n        network_config: None,\n    });\n    l.connection\n        .check()\n        .map_err(|err| Error::new(ErrorKind::InvalidInput, err.to_string()))?;\n    Ok(sp)\n}\n\n// The FileSystem scheme of WebHDFS is “webhdfs://”. A WebHDFS FileSystem URI has the following format.\n// webhdfs://<HOST>:<HTTP_PORT>/<PATH>","sourceCodeStart":371,"sourceCodeEnd":407,"githubUrl":"https://github.com/databendlabs/databend/blob/288d84d76e20a2f8f7173bda9691eb6ece301aa9/src/query/sql/src/planner/binder/location.rs#L371-L407","documentation":"The hdfs:// scheme requires a name node address, but neither the URI (no host part) nor the connection options provided 'name_node'. parse_hdfs_params cannot construct a StorageHdfsConfig without it, so it fails with InvalidInput. The message notes the options-based form is preferred.","triggerScenarios":"A location like 'hdfs:///data/path' (empty authority) or 'hdfs://path' with no name_node option in CONNECTION, during CREATE STAGE or COPY binding.","commonSituations":"Copying S3-style stage definitions and switching the scheme to hdfs without adding name_node; forgetting that HDFS unlike object stores needs an explicit name node; URI with relative path but missing host.","solutions":["Add the name_node connection option: CONNECTION = (name_node = 'name-node-host:8020').","Alternatively include the host in the URI: hdfs://name-node-host:8020/path/.","Verify the URI actually carries an authority (hdfs://host/path, not hdfs:///path) when relying on it."],"exampleFix":"// before\nCREATE STAGE s URL = 'hdfs:///warehouse/';\n// after\nCREATE STAGE s URL = 'hdfs:///warehouse/' CONNECTION = (name_node = 'nn.example.com:8020');","handlingStrategy":"validation","validationCode":"// Rust\nlet has_uri_nn = !uri_authority.is_empty();\nlet has_opt = conn_opts.contains_key(\"name_node\");\nif scheme == \"hdfs\" && !has_uri_nn && !has_opt { panic!(\"hdfs requires name_node\"); }","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always include host:port in hdfs:// URIs or set the name_node option.","Keep a documented stage template for HDFS that includes name_node.","Never port S3-style stage definitions to HDFS without adding the name node."],"tags":["storage","hdfs","missing-config","uri-parsing"],"backgroundTag":"missing-required-config-field","analyzedSha":"288d84d76e20a2f8f7173bda9691eb6ece301aa9","analyzedAt":"2026-09-11T11:29:36.208Z","contentChangedAt":"2026-09-11T11:29:36.208Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}