apache/dolphinscheduler · error · RuntimeException

Put request execute failed, url: %s

Error message

Put request execute failed, url: %s

What it means

OkHttpUtils.put() wraps any failure while executing an OkHttp PUT call (connection errors, timeouts, IO errors, non-recoverable client problems) into a RuntimeException that names the target URL. The original exception is preserved as the cause. It signals the HTTP PUT request never completed successfully at the transport layer.

Source

Thrown at dolphinscheduler-common/src/main/java/org/apache/dolphinscheduler/common/utils/OkHttpUtils.java:125

     */
    public static @NonNull OkHttpResponse put(@NonNull String url,
                                              @Nullable OkHttpRequestHeaders okHttpRequestHeaders,
                                              @Nullable Map<String, Object> requestBodyMap,
                                              int connectTimeout,
                                              int writeTimeout,
                                              int readTimeout) throws IOException {
        OkHttpClient client = getHttpClient(connectTimeout, writeTimeout, readTimeout);
        Request.Builder requestBuilder = new Request.Builder().url(url);
        addHeader(okHttpRequestHeaders.getHeaders(), requestBuilder);
        if (requestBodyMap != null) {
            requestBuilder = requestBuilder.put(RequestBody.create(
                    JSONUtils.toJsonString(requestBodyMap),
                    MediaType.parse(okHttpRequestHeaders.getOkHttpRequestHeaderContentType().getValue())));
        }
        try (Response response = client.newCall(requestBuilder.build()).execute()) {
            return new OkHttpResponse(response.code(), getResponseBody(response));
        } catch (Exception e) {
            throw new RuntimeException(String.format("Put request execute failed, url: %s", url), e);
        }
    }

    /**
     * http delete request
     * @param connectTimeout connect timeout in milliseconds
     * @param writeTimeout write timeout in milliseconds
     * @param readTimeout read timeout in milliseconds
     * @return OkHttpResponse
     * @throws RuntimeException
     */
    public static @NonNull OkHttpResponse delete(@NonNull String url,
                                                 @Nullable OkHttpRequestHeaders okHttpRequestHeaders,
                                                 int connectTimeout,
                                                 int writeTimeout,
                                                 int readTimeout) throws IOException {
        OkHttpClient client = getHttpClient(connectTimeout, writeTimeout, readTimeout);
        Request.Builder requestBuilder = new Request.Builder().url(url);

View on GitHub (pinned to 02eac45a1b)

Solutions

  1. Verify the target URL is reachable (curl -X PUT the same URL from the same host).
  2. Check the wrapped cause in the stack trace to distinguish connect timeout, refused connection, or TLS error.
  3. Increase connectTimeout/readTimeout passed to put(...) if the server is slow.
  4. Ensure the remote service is running and network/firewall allows the connection.

Example fix

// before
OkHttpUtils.put(url, params, headers);
// after
try {
    OkHttpResponse resp = OkHttpUtils.put(url, params, headers);
} catch (RuntimeException e) {
    log.error("PUT to {} failed: {}", url, e.getCause(), e);
    throw new ServiceException("Upstream PUT failed", e);
}
Defensive patterns

Strategy: try-catch

Validate before calling

HttpUrl parsed = HttpUrl.parse(url);
if (parsed == null) throw new IllegalArgumentException("Bad PUT url: " + url);

Try / catch

try {
    OkHttpResponse r = OkHttpUtils.put(url, params, headers);
} catch (RuntimeException e) {
    log.error("PUT {} failed: {}", url, e.getCause(), e);
    throw new ServiceException(e);
}

Prevention

When it happens

Trigger: Calling OkHttpUtils.put(...) when the server is unreachable, connection is refused or reset, TLS handshake fails, read/connect timeout elapses, or the response body cannot be read inside client.newCall(...).execute().

Common situations: Target service down or wrong port in configured URL; DNS misconfiguration; firewall blocking outbound calls; slow endpoint exceeding the configured connectTimeout; calling an HTTPS endpoint with a bad certificate trust store.

Understand the failure class

Background: 'Something went wrong' / 'Request failed (500)' / 'HTTP error! status: 404' — what failed HTTP requests actually mean and how to find the real cause — this error's family across 28 libraries.

Related errors

AI-assisted analysis of apache/dolphinscheduler@02eac45a1b (2026-09-06). Data as JSON: /api/errors/11bc11931dd2f7d9. Report an issue: GitHub.