{"record":{"id":"c24b959e7e9e0cf6","repo":"apache/hadoop","slug":"the-ingress-service-type-must-be-configured-as-dfs","errorCode":null,"errorMessage":"The ingress service type must be configured as DFS","messagePattern":"The ingress service type must be configured as DFS","errorType":"validation","errorClass":"InvalidConfigurationValueException","httpStatus":null,"severity":"error","filePath":"hadoop-tools/hadoop-azure/src/main/java/org/apache/hadoop/fs/azurebfs/services/AbfsOutputStream.java","lineNumber":302,"sourceCode":"      }\n    }\n    // If ingressHandler is null, no lock is needed; safely initialize it outside the lock\n    return createNewHandler(serviceType, blockFactory, bufferSize, isSwitch, blockManager);\n  }\n\n  // Helper method to create a new handler, used in both scenarios (locked and unlocked)\n  private AzureIngressHandler createNewHandler(AbfsServiceType serviceType,\n      DataBlocks.BlockFactory blockFactory,\n      int bufferSize,\n      boolean isSwitch,\n      AzureBlockManager blockManager) throws IOException {\n    this.client = clientHandler.getClient(serviceType);\n\n    // Check ingress service type is also set to DFS along with enabling the config for fallback\n    // Separate ingress service type is only allowed for HNS accounts\n    if (isDFSToBlobFallbackEnabled && client.getIsNamespaceEnabled()\n        && serviceTypeAtInit != AbfsServiceType.DFS) {\n      throw new InvalidConfigurationValueException(\n          \"The ingress service type must be configured as DFS\");\n    }\n    if (isDFSToBlobFallbackEnabled && !isSwitch) {\n      ingressHandler = new AzureDfsToBlobIngressFallbackHandler(this,\n          blockFactory, bufferSize, eTag, clientHandler);\n    } else if (serviceType == AbfsServiceType.BLOB) {\n      ingressHandler = new AzureBlobIngressHandler(this, blockFactory,\n          bufferSize, eTag, clientHandler, blockManager);\n    } else {\n      ingressHandler = new AzureDFSIngressHandler(this, blockFactory,\n          bufferSize, eTag, clientHandler);\n    }\n    if (isSwitch) {\n      switchCompleted = true;\n    }\n    return ingressHandler;\n  }\n","sourceCodeStart":284,"sourceCodeEnd":320,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-tools/hadoop-azure/src/main/java/org/apache/hadoop/fs/azurebfs/services/AbfsOutputStream.java#L284-L320","documentation":"AbfsOutputStream.createNewHandler throws InvalidConfigurationValueException(\"The ingress service type must be configured as DFS\") when three conditions coincide: fs.azure.enable.dfstoblob.fallback is true, the account is hierarchical-namespace enabled (HNS), and the configured ingress service type (fs.azure.ingress.service.type) at stream creation is not DFS. The DFS-to-blob fallback uploads via DFS and falls back to blob endpoints, so a separate blob ingress on an HNS account is rejected up front.","triggerScenarios":"Setting fs.azure.ingress.service.type=BLOB (to write through the blob endpoint) while also enabling fs.azure.enable.dfstoblob.fallback=true on an HNS-enabled storage account; enabling the fallback knob in tuning guides without checking the ingress type already set for throughput reasons.","commonSituations":"Performance tuning where blob ingress was configured first and the fallback flag added later; config reuse across accounts where one account is HNS and another is not; version upgrades that added the guard to previously permissive combinations.","solutions":["Set fs.azure.ingress.service.type=DFS (or remove it) when fs.azure.enable.dfstoblob.fallback is true","Or set fs.azure.enable.dfstoblob.fallback=false if blob ingress is what you want","Remember the guard applies to HNS accounts only — a flat (non-HNS) account does not trip it"],"exampleFix":"<!-- before: conflicting combination on an HNS account -->\n<property>\n  <name>fs.azure.enable.dfstoblob.fallback</name>\n  <value>true</value>\n</property>\n<property>\n  <name>fs.azure.ingress.service.type</name>\n  <value>Blob</value>\n</property>\n\n<!-- after -->\n<property>\n  <name>fs.azure.enable.dfstoblob.fallback</name>\n  <value>true</value>\n</property>\n<property>\n  <name>fs.azure.ingress.service.type</name>\n  <value>DFS</value>\n</property>","handlingStrategy":"validation","validationCode":"// Reject the conflicting combination before mounting the FS\nboolean fallback = conf.getBoolean(\"fs.azure.enable.dfstoblob.fallback\", false);\nString ingress = conf.get(\"fs.azure.ingress.service.type\");\nif (fallback && hnsEnabled && !\"DFS\".equalsIgnoreCase(ingress == null ? \"DFS\" : ingress)) {\n  throw new IllegalArgumentException(\n      \"fs.azure.ingress.service.type must be DFS when\"\n      + \" fs.azure.enable.dfstoblob.fallback=true on an HNS account\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["When enabling the DFS-to-blob fallback on HNS accounts, always set ingress type to DFS","Lint abfs configs for mutually exclusive flag combinations at deploy time","Track which accounts are HNS-enabled; the guard only fires for those"],"tags":["azure-blob","abfs","configuration","hns","dfs","ingress","hadoop"],"backgroundTag":"invalid-configuration","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}