{"record":{"id":"4654bd187bd1d9b6","repo":"apache/seatunnel","slug":"shallow-key-discovery-failed-on-path-falling","errorCode":null,"errorMessage":"Shallow key discovery failed on path [{}]. Falling back to Single Path Split. Reason: {}","messagePattern":"Shallow key discovery failed on path \\[(.+?)\\]\\. Falling back to Single Path Split\\. Reason: (.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"seatunnel-connectors-v2/connector-firebase/src/main/java/org/apache/seatunnel/connectors/seatunnel/firebase/source/FirebaseSourceSplitEnumerator.java","lineNumber":109,"sourceCode":"            }\n        }\n        String basePath = config.get(FirebaseSourceOptions.PATH);\n        List<FirebaseSourceSplit> generatedSplits = new ArrayList<>();\n\n        try {\n            log.info(\"Attempting automatic key discovery (shallow scan) on path [{}]\", basePath);\n            List<String> keys = httpClient.fetchShallowKeys();\n            if (!keys.isEmpty()) {\n                generatedSplits = partitionKeysIntoSplits(basePath, keys);\n                log.info(\n                        \"Key discovery succeeded. Partitioned path into {} splits.\",\n                        generatedSplits.size());\n            } else {\n                log.info(\"Shallow scan returned no child keys. Falling back to Single Path Split.\");\n                generatedSplits.add(createSinglePathSplit(basePath));\n            }\n        } catch (Exception e) {\n            log.warn(\n                    \"Shallow key discovery failed on path [{}]. \"\n                            + \"Falling back to Single Path Split. Reason: {}\",\n                    basePath,\n                    e.getMessage());\n            generatedSplits.add(createSinglePathSplit(basePath));\n        }\n        synchronized (this) {\n            pendingSplits.addAll(generatedSplits);\n            log.info(\"pending Splits : {}\", pendingSplits);\n            this.discoveryDone = true;\n            assignSplits();\n        }\n    }\n\n    @Override\n    public synchronized void registerReader(int subtaskId) {\n        log.info(\"Reader subtask [{}] registered.\", subtaskId);\n        assignSplits();","sourceCodeStart":91,"sourceCodeEnd":127,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-connectors-v2/connector-firebase/src/main/java/org/apache/seatunnel/connectors/seatunnel/firebase/source/FirebaseSourceSplitEnumerator.java#L91-L127","documentation":"The Firebase source split enumerator first attempts a shallow scan of the configured base path to discover child keys and generate one split per child. If the shallow scan throws any exception (or returns no keys), the enumerator logs this warning and falls back to generating a single split covering the whole base path instead of failing the job. Data is still read, but with reduced parallelism since only one split is produced.","triggerScenarios":"Calling run() on FirebaseSourceSplitEnumerator when the shallow key discovery REST/SDK call throws — e.g. the base path does not exist, network/permission errors during the shallow scan, or the scan unexpectedly returns an empty key list.","commonSituations":"Misconfigured or renamed Firebase Realtime Database path; restrictive database security rules blocking read at the parent path; transient network failures to Firebase; genuinely empty child collections at the base path.","solutions":["Check that the configured base path exists and is readable under the database's security rules; fix the path or rules so the shallow scan succeeds.","Inspect the 'Reason' in the warning log to identify the underlying exception (auth, network, not-found) and fix that root cause.","Accept the fallback if single-path parallelism is sufficient for your data volume.","Retry the job if the failure was transient (network blip); the enumerator will re-run shallow discovery."],"exampleFix":"// before (path blocked by rules)\nbasePath = \"/orders/2026\"\n// after (grant read on that subtree in Firebase rules)\n{ \"rules\": { \"orders\": { \"2026\": { \".read\": true } } } }","handlingStrategy":"fallback","validationCode":"// before submitting the job, verify the path is readable\nFirebase foo = new Firebase(\"https://<db>.firebaseio.com\");\nfoo.child(basePath).once(\"value\", snap => console.log(snap.numChildren()), err => console.error(err));","typeGuard":null,"tryCatchPattern":"try {\n    enumerator.run();\n} catch (Exception e) {\n    // shallow-discovery failures are internally handled; reaching here means deeper failure\n    log.error(\"Split enumeration failed beyond fallback: {}\", e.getMessage(), e);\n}","preventionTips":["Validate the Firebase base path exists and security rules allow read before starting the job.","Watch for this warning and treat it as a parallelism degradation signal, not silent success.","Grant read permission at the parent level so shallow scans of children succeed.","Monitor the Reason field in the log to distinguish transient network errors from config errors."],"tags":["firebase","split-enumerator","fallback","parallelism","log-warn"],"backgroundTag":"fallback-path-taken","analyzedSha":"cf67b549a7a6c35fa0beb12d83c62892427ea919","analyzedAt":"2026-09-10T21:44:55.265Z","contentChangedAt":"2026-09-10T21:44:55.265Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}