apache/dolphinscheduler · error · GrpcTaskException

gRPC handle exception:

Error message

gRPC handle exception:

What it means

GrpcTask.handle() builds a channel/stub and invokes the configured gRPC method. Any unexpected exception during the call (channel creation, message construction, serialization, or non-status runtime errors not caught as StatusRuntimeException) is wrapped as GrpcTaskException('gRPC handle exception:'). StatusRuntimeException is handled separately via validateResponse, so this indicates an error outside the normal gRPC status path.

Source

Thrown at dolphinscheduler-task-plugin/dolphinscheduler-task-grpc/src/main/java/org/apache/dolphinscheduler/plugin/task/grpc/GrpcTask.java:93

            ManagedChannel channel;
            if (grpcParameters.getChannelCredentialType() == GrpcCredentialType.TLS_DEFAULT) {
                TlsChannelCredentials creds = (TlsChannelCredentials) TlsChannelCredentials.create();
                channel = GrpcDynamicService.ChannelFactory.createChannel(grpcParameters.getUrl(), creds);
            } else {
                channel = GrpcDynamicService.ChannelFactory.createChannel(grpcParameters.getUrl());
            }
            Descriptors.FileDescriptor fileDesc =
                    JSONDescriptorHelper.fileDescFromJSON(grpcParameters.getGrpcServiceDefinitionJSON());
            GrpcDynamicService stubService = new GrpcDynamicService(channel, fileDesc);
            DynamicMessage message = stubService.call(grpcParameters.getMethodName(), grpcParameters.getMessage(),
                    grpcParameters.getConnectTimeoutMs());
            Printer printer = JsonFormat.printer().omittingInsignificantWhitespace();
            addDefaultOutput(printer.print(message));
        } catch (StatusRuntimeException statusre) {
            validateResponse(statusre.getStatus());
            return;
        } catch (Exception e) {
            throw new GrpcTaskException("gRPC handle exception:", e);
        }
        validateResponse(Status.OK);
    }

    @Override
    public void cancel() throws TaskException {
        // Do nothing when task to be canceled
    }

    private void validateResponse(Status statusCode) {
        switch (grpcParameters.getGrpcCheckCondition()) {
            case STATUS_CODE_DEFAULT:
                if (!statusCode.isOk()) {
                    log.error(
                            "grpc request failed, url: {}, method: {}, statusCode: {} (expected OK), checkCondition: {}",
                            grpcParameters.getUrl(), grpcParameters.getMethodName(), statusCode.getCode(),
                            GrpcCheckCondition.STATUS_CODE_DEFAULT.name());
                    exitStatusCode = TaskConstants.EXIT_CODE_FAILURE;

View on GitHub (pinned to 02eac45a1b)

Solutions

1. Check the wrapped cause 'e' in the worker logs for the real failure (parse error vs network error)
2. Validate the request body JSON against the proto message field names/types
3. Verify the gRPC target address and TLS settings are reachable from the worker
4. Fix parameter values in the task form and re-run

Example fix

// before
throw new GrpcTaskException("gRPC handle exception:", e);
// after
throw new GrpcTaskException("gRPC handle exception for url=" + grpcParameters.getUrl() + ", method=" + grpcParameters.getMethodName(), e);

// validate request JSON against proto before calling
Message.Builder b = descriptor.findMessageTypeByName(requestMessageType).toProto().toBuilder();
JsonFormat.parser().ignoringUnknownFields().merge(requestJson, b); // throws if field types mismatch

try {
    task.handle(null);
} catch (GrpcTaskException e) {
    Throwable cause = e.getCause();
    if (cause instanceof StatusRuntimeException) { /* handled by validateResponse path */ }
    else if (cause instanceof InvalidProtocolBufferException) { /* fix request body */ }
    else { /* network/channel issue: check target and TLS */ }
}

When it happens

Trigger: Exception while parsing request JSON into the protobuf message, building the channel (bad target/host), JsonFormat.printer failures on the response, or any non-StatusRuntimeException from the stub call.

Common situations: Invalid request parameter values that fail protobuf JSON parsing; malformed grpc target URL; TLS/network misconfig throwing IO exceptions inside the stub; proto message field type mismatches in request body.

Related errors

• gRPC task params is not valid, method definition may not cor
• cannot find service <serviceName> from service definition
• cannot find method <rpcName> from service <serviceName> with
• cannot merge json message to protobuf definition type <messa
• grpc exception: Unrecognized field label:

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