apache/seatunnel · error · FileConnectorException

CONFIG_VALIDATION_FAILED

CONFIG_VALIDATION_FAILED

Error message

Cannot derive a safe logical source identity for Markdown input

What it means

MarkdownKnowledgeSyncMetadata.canonicalizeSourceUri derives a stable logical identity for a Markdown source. A null or whitespace-only sourceUri cannot identify anything, so it throws the unsafe-source-identity error (CONFIG_VALIDATION_FAILED) before the job starts reading files.

Solutions

1. Set the source path/URI option in the Markdown source config (a valid local path or hierarchical remote URI)
2. Check templated/variable-substituted config values actually resolved to non-empty strings at submit time
3. Validate config before submission; fail fast on empty required fields
4. If the path is intentionally optional, guard the call site and skip identity derivation

Example fix

// before
MarkdownKnowledgeSyncMetadata.canonicalizeSourceUri(config.get("path")); // path unset -> null
// after
String uri = config.getString("path");
Objects.requireNonNull(uri, "Markdown source path must be set");
MarkdownKnowledgeSyncMetadata.canonicalizeSourceUri(uri);

String uri = config.getString("path");
if (uri == null || uri.trim().isEmpty())
    throw new IllegalArgumentException("Markdown source path must be set");

boolean hasSourceUri(String s) { return s != null && !s.trim().isEmpty(); }

try {
    String canonical = MarkdownKnowledgeSyncMetadata.canonicalizeSourceUri(uri);
} catch (RuntimeException e) {
    if (String.valueOf(e.getMessage()).contains("safe logical source identity")) {
        // fail config validation with a clear 'path is required' message
    }
}

When it happens

Trigger: Calling canonicalizeSourceUri (directly or via safeSourceContext) with sourceUri == null or sourceUri.trim().isEmpty() — typically because the file path/URI option was not populated in the connector config.

Common situations: Missing file path/URI in the Markdown source config; config templating left the placeholder empty; programmatic use passing an unset variable.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• All candidate sink tables were skipped during job parsing.
• AmazonDocumentDB option 'uri' must include authentication…
• batch_size must be >= 1, got:
• Binary chunk size must be positive, got
• Binary chunk size too large (max 100MB), got

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/c7af8f9c332816a8. Report an issue: GitHub.

Appendix: source

Thrown at seatunnel-connectors-v2/connector-file/connector-file-base/src/main/java/org/apache/seatunnel/connectors/seatunnel/file/source/MarkdownKnowledgeSyncMetadata.java:60

    private static final char[] HEX_CHARS = "0123456789abcdef".toCharArray();
    private static final KnowledgeSyncMetadataField[] BRIDGE_FIELDS = {
        KnowledgeSyncMetadataField.SOURCE_URI,
        KnowledgeSyncMetadataField.DOCUMENT_ID,
        KnowledgeSyncMetadataField.DOCUMENT_HASH,
        KnowledgeSyncMetadataField.CHUNK_HASH
    };

    private MarkdownKnowledgeSyncMetadata() {}

    /**
     * Builds a credential-free logical source identity without changing legacy physical identity.
     *
     * @param sourceUri physical source path or URI
     * @return normalized local path or sanitized hierarchical remote URI
     */
    public static String canonicalizeSourceUri(String sourceUri) {
        if (sourceUri == null || sourceUri.trim().isEmpty()) {
            throw unsafeSourceIdentityException();
        }
        if (isWindowsLocalPath(sourceUri)) {
            return sourceUri;
        }

        URI uri;
        try {
            uri = new URI(sourceUri);
        } catch (URISyntaxException e) {
            if (looksLikeUri(sourceUri)) {
                throw unsafeSourceIdentityException();
            }
            return sourceUri;
        }

        if (uri.getScheme() == null) {
            return sourceUri;
        }

View on GitHub (pinned to cf67b549a7)