{"record":{"id":"26094ee1823270b3","repo":"apache/flink","slug":"error-parsing-yaml-configuration","errorCode":null,"errorMessage":"Error parsing YAML configuration.","messagePattern":"Error parsing YAML configuration\\.","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"flink-core/src/main/java/org/apache/flink/configuration/ConfigurationFileMigrationUtils.java","lineNumber":168,"sourceCode":"                    String key = kv[0].trim();\n                    String value = kv[1].trim();\n\n                    // sanity check\n                    if (key.length() == 0 || value.length() == 0) {\n                        LOG.warn(\n                                \"Error after splitting key and value in configuration file \"\n                                        + file\n                                        + \":\"\n                                        + lineNo\n                                        + \": Key or value was empty\");\n                        continue;\n                    }\n\n                    config.put(key, value);\n                }\n            }\n        } catch (IOException e) {\n            throw new RuntimeException(\"Error parsing YAML configuration.\", e);\n        }\n\n        return config;\n    }\n}\n","sourceCodeStart":150,"sourceCodeEnd":174,"githubUrl":"https://github.com/apache/flink/blob/2f3c205e9266cb30240eb7f4fdab15cad629a70f/flink-core/src/main/java/org/apache/flink/configuration/ConfigurationFileMigrationUtils.java#L150-L174","documentation":"The innermost failure of legacy config loading: loadLegacyYAMLResource parses flink-conf.yaml line by line (splitting key: value); any IOException while reading the file (and per-line validation errors funnel through the same catch in some paths) is rethrown as RuntimeException 'Error parsing YAML configuration.'. This is an I/O-level failure reading the file, distinct from the semantic per-line 'key or value was empty' warnings which are skipped, not thrown.","triggerScenarios":"An actual IOException while reading flink-conf.yaml: file deleted between the exists() check and opening; permission denied on the file; a directory named flink-conf.yaml; a broken symlink; unreadable mount in a container.","commonSituations":"Race where config is replaced atomically (rename) while Flink reads it; restrictive file permissions (owned by another user, mode 600 with a different runtime user); Kubernetes projected config volumes with permission issues.","solutions":["Verify the file is readable by the Flink process user: 'ls -l' and 'cat' it as that user; fix chmod/chown (e.g. 644).","If configs are swapped via rename, ensure readers open the old inode (atomically replaced files are fine; in-place truncate+write is not) — prefer atomic move-over.","Repair broken symlinks / ensure the mounted volume actually exposes the file.","Check the nested IOException cause for the precise reason before retrying."],"exampleFix":"# before\n-rw------- 1 root root 640 flink-conf.yaml  # flink user cannot read\n\n# after\nchown flink:flink flink-conf.yaml && chmod 644 flink-conf.yaml","handlingStrategy":"try-catch","validationCode":"Path p = Paths.get(configDir, \"flink-conf.yaml\");\nif (!Files.isReadable(p)) {\n    throw new IllegalStateException(\"Config file not readable by user \" + System.getProperty(\"user.name\") + \": \" + p);\n}","typeGuard":null,"tryCatchPattern":"try {\n    Configuration conf = ConfigurationFileMigrationUtils.migrateLegacyToStandardYamlConfig(dir);\n} catch (RuntimeException e) {\n    if (\"Error parsing YAML configuration.\".equals(e.getMessage()) && e.getCause() instanceof IOException) {\n        // I/O failure reading the file (permissions/renamed/unmounted): inspect cause, fix, retry\n    }\n    throw e;\n}","preventionTips":["Ship config files with mode 644 owned by the service user; verify readability in deployment checks.","Replace config files atomically (write temp + rename) so readers never see partial states.","Mount Kubernetes config volumes read-only and confirm projection succeeded before starting Flink."],"tags":["configuration","io","permissions","startup","flink-core"],"backgroundTag":null,"analyzedSha":"2f3c205e9266cb30240eb7f4fdab15cad629a70f","analyzedAt":"2026-08-14T08:48:24.518Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}