apache/flink · error · RuntimeException

Error parsing YAML configuration.

Error message

Error parsing YAML configuration.

What it means

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.

Source

Thrown at flink-core/src/main/java/org/apache/flink/configuration/ConfigurationFileMigrationUtils.java:168

                    String key = kv[0].trim();
                    String value = kv[1].trim();

                    // sanity check
                    if (key.length() == 0 || value.length() == 0) {
                        LOG.warn(
                                "Error after splitting key and value in configuration file "
                                        + file
                                        + ":"
                                        + lineNo
                                        + ": Key or value was empty");
                        continue;
                    }

                    config.put(key, value);
                }
            }
        } catch (IOException e) {
            throw new RuntimeException("Error parsing YAML configuration.", e);
        }

        return config;
    }
}

View on GitHub (pinned to 2f3c205e92)

Solutions

1. Verify the file is readable by the Flink process user: 'ls -l' and 'cat' it as that user; fix chmod/chown (e.g. 644).
2. 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.
3. Repair broken symlinks / ensure the mounted volume actually exposes the file.
4. Check the nested IOException cause for the precise reason before retrying.

Example fix

# before
-rw------- 1 root root 640 flink-conf.yaml  # flink user cannot read

# after
chown flink:flink flink-conf.yaml && chmod 644 flink-conf.yaml

Path p = Paths.get(configDir, "flink-conf.yaml");
if (!Files.isReadable(p)) {
    throw new IllegalStateException("Config file not readable by user " + System.getProperty("user.name") + ": " + p);
}

try {
    Configuration conf = ConfigurationFileMigrationUtils.migrateLegacyToStandardYamlConfig(dir);
} catch (RuntimeException e) {
    if ("Error parsing YAML configuration.".equals(e.getMessage()) && e.getCause() instanceof IOException) {
        // I/O failure reading the file (permissions/renamed/unmounted): inspect cause, fix, retry
    }
    throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Given configuration directory is null, cannot load configura
• The given configuration directory name '{}' ({}) does not de
• The Flink config file '{}' ({}) does not exist.
• Exception when trying to initialize plugin system.
• Could not register security manager due to no permission to

AI-assisted analysis of apache/flink@2f3c205e92 (2026-08-14). Data as JSON: /api/errors/26094ee1823270b3. Report an issue: GitHub.