pinpoint-apm/pinpoint · error · IllegalArgumentException

Webhook URL host is required

Error message

Webhook URL host is required

What it means

WebhookUrlValidator.validateAuthority throws IllegalArgumentException when the parsed URI has no host component (getHost() null or blank). Even with a valid scheme, an HTTP webhook needs a resolvable host.

Source

Thrown at commons-server/src/main/java/com/navercorp/pinpoint/common/server/webhook/WebhookUrlValidator.java:120

        return uri;
    }

    private static void validateScheme(URI uri) {
        String scheme = uri.getScheme();
        if (scheme == null) {
            throw new IllegalArgumentException("Webhook URL scheme is required");
        }

        String normalizedScheme = scheme.toLowerCase(Locale.ROOT);
        if (!"http".equals(normalizedScheme) && !"https".equals(normalizedScheme)) {
            throw new IllegalArgumentException("Webhook URL scheme must be http or https");
        }
    }

    private static void validateAuthority(URI uri) {
        if (uri.getHost() == null || uri.getHost().isBlank()) {
            throw new IllegalArgumentException("Webhook URL host is required");
        }
        if (isBlockedHostLiteral(uri.getHost())) {
            throw new IllegalArgumentException("Webhook URL host is not allowed");
        }
        if (uri.getRawUserInfo() != null) {
            throw new IllegalArgumentException("Webhook URL user info is not allowed");
        }
        if (uri.getRawFragment() != null) {
            throw new IllegalArgumentException("Webhook URL fragment is not allowed");
        }
        int port = uri.getPort();
        if (port == -1 && hasExplicitPort(uri)) {
            throw new IllegalArgumentException("Webhook URL port is not valid");
        }
        if (port == 0 || port > MAX_PORT) {
            throw new IllegalArgumentException("Webhook URL port is not allowed");
        }
    }

View on GitHub (pinned to 744c3d3075)

Solutions

1. Include a host in the URL: https://example.com/hook
2. Validate that the configured endpoint host resolves (DNS) before saving the webhook
3. Check for copy/paste truncation of the URL in the config source

Example fix

// before
validator.validateSyntax("https:///webhook");
// after
validator.validateSyntax("https://example.com/webhook");

if (!url.matches("^https?://[^/]+.*")) reject(url);

boolean hasHost(java.net.URI uri) { return uri.getHost() != null && !uri.getHost().isBlank(); }

try { WebhookUrlValidator.validateSyntax(url); } catch (IllegalArgumentException e) { if (e.getMessage().contains("host is required")) { form.reject("url", "host is missing"); } }

When it happens

Trigger: URLs like 'http://' or 'https:///path' where the authority part is empty; a URL whose authority failed to parse so getHost() returns null.

Common situations: Truncated URL in config after the host was accidentally deleted; 'http://%20' style garbage input; form submitted with only scheme typed.

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

• Webhook URL is required
• Malformed webhook URL
• Webhook URL scheme is required
• Webhook URL scheme must be http or https
• Webhook URL fragment is not allowed

AI-assisted analysis of pinpoint-apm/pinpoint@744c3d3075 (2026-09-07). Data as JSON: /api/errors/1708642ec0aea260. Report an issue: GitHub.