apache/seatunnel · error · OptionValidationException

Invalid SqlServer JDBC URL format

Error message

Invalid SqlServer JDBC URL format: [%s], expected pattern: jdbc:sqlserver://host:port[;databaseName=db]

What it means

The SQL Server JDBC URL validator in SqlServerCatalogFactory.evaluate() parses the URL with SqlServerURLParser; if parsing throws IllegalArgumentException (URL does not match jdbc:sqlserver://host:port[;databaseName=db]), it throws OptionValidationException with the expected pattern. This is a config-time guard so malformed SQL Server URLs fail fast instead of at connection time.

Solutions

1. Rewrite the URL as jdbc:sqlserver://host:port (optionally ;databaseName=mydb), e.g. jdbc:sqlserver://mssql-host:1433;databaseName=master.
2. Verify the scheme is exactly jdbc:sqlserver:// with host and numeric port present.
3. If using a named instance, convert it to the resolved port form (e.g. 1433) so the URL matches the expected pattern.
4. Trim whitespace/quotes from the config value and re-validate.

Example fix

// before
url = "jdbc:sqlserver://mssql-host\\SQLEXPRESS"
// after
url = "jdbc:sqlserver://mssql-host:1433;databaseName=mydb"

// java
String url = config.get("url");
if (url == null || !url.matches("jdbc:sqlserver://[^:/\\s]+:\\d+([;\\S]*)?")) {
    throw new IllegalArgumentException("SqlServer url must match jdbc:sqlserver://host:port[;databaseName=db]");
}

When it happens

Trigger: Configuring a SQL Server catalog/connection with a url that does not start with jdbc:sqlserver:// or lacks a valid host:port — e.g. jdbc:sqlserver:host (missing //), jdbc:sqlserver://host (no port where the parser requires one), or a scheme for a different database.

Common situations: Mixing up SQL Server URL styles (named-instance URLs like jdbc:sqlserver://host\instance may not match the strict pattern); missing port; copying a SQL Authentication string with the database parameter malformed (;databaseName= without value).

Understand the failure class

Background: "Invalid URL" errors: why new URL(), URI.parse, and reqwest::Url reject your string — missing scheme, whitespace, and bad path format — this error's family across 39 libraries.

Related errors

• Invalid SAP HANA JDBC URL format
• Invalid YashanDB JDBC URL
• All candidate sink tables were skipped during job parsing.
• AmazonDocumentDB option 'uri' must include authentication…
• batch_size must be >= 1, got:

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

Appendix: source

Thrown at seatunnel-connectors-v2/connector-jdbc/src/main/java/org/apache/seatunnel/connectors/seatunnel/jdbc/catalog/sqlserver/SqlServerCatalogFactory.java:77

    }

    /** Validates URL format only; database may be provided via separate config option. */
    static class SqlServerUrlValidator implements ConditionExtension<String> {
        @Override
        public String description() {
            return "SqlServer JDBC URL must be a valid format (e.g. jdbc:sqlserver://host:port;databaseName=db)";
        }

        @Override
        public boolean evaluate(ReadonlyConfig config, String url) {
            if (url == null || url.trim().isEmpty()) {
                return false;
            }
            try {
                JdbcUrlUtil.UrlInfo info = SqlServerURLParser.parse(url);
                return info != null && StringUtils.isNotBlank(info.getHost());
            } catch (IllegalArgumentException e) {
                throw new OptionValidationException(
                        String.format(
                                "Invalid SqlServer JDBC URL format: [%s], "
                                        + "expected pattern: jdbc:sqlserver://host:port[;databaseName=db]",
                                url));
            }
        }
    }
}

View on GitHub (pinned to cf67b549a7)