apache/dolphinscheduler · error · GrpcTaskException

gRPC task params is not valid, method definition may not cor

Error message

gRPC task params is not valid, method definition may not corresponds to message or method name is invalid

What it means

GrpcTask.init() parses taskParams into GrpcParameters and validates them via checkParameters(), which verifies the proto method definition corresponds to the configured message and method name. Failure throws GrpcTaskException('gRPC task params is not valid, ...'). This prevents invoking a gRPC endpoint with an unusable/inconsistent method definition.

Source

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

    private TaskExecutionContext taskExecutionContext;

    /**
     * constructor
     *
     * @param taskExecutionContext taskExecutionContext
     */
    protected GrpcTask(TaskExecutionContext taskExecutionContext) {
        super(taskExecutionContext);
        this.taskExecutionContext = taskExecutionContext;
    }

    @Override
    public void init() {
        this.grpcParameters = JSONUtils.parseObject(taskExecutionContext.getTaskParams(), GrpcParameters.class);
        log.info("Initialize gRPC task params: {}", JSONUtils.toPrettyJsonString(grpcParameters));

        if (grpcParameters == null || !grpcParameters.checkParameters()) {
            throw new GrpcTaskException(
                    "gRPC task params is not valid, method definition may not corresponds to message or method name is invalid");
        }
    }

    @Override
    public void handle(TaskCallBack taskCallBack) throws TaskException {
        try {
            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(),

View on GitHub (pinned to 02eac45a1b)

Solutions

1. Verify the methodName matches a method declared in the attached proto file's service
2. Re-upload/select the correct .proto file in the task definition and confirm message names match
3. Ensure url and other required gRPC parameters are non-empty
4. Re-save and re-run the task so params are re-parsed

Example fix

// before
{"url":"localhost:50051","methodName":"Foo/Bar"}
// after
{"url":"localhost:50051","methodName":"com.example.MyService/GetItem","protoFile":"my_service.proto"}

GrpcParameters p = JSONUtils.parseObject(taskParams, GrpcParameters.class);
if (p == null || !p.checkParameters()) {
    throw new IllegalArgumentException("grpc params invalid: check url, methodName and attached proto file");
}

boolean isValidGrpcParams(String json) {
    GrpcParameters p = JSONUtils.parseObject(json, GrpcParameters.class);
    return p != null && p.checkParameters();
}

try {
    task.init();
} catch (GrpcTaskException e) {
    log.error("grpc params invalid: {}", e.getMessage());
    // correct proto/methodName in the task definition
}

When it happens

Trigger: grpcParameters null or checkParameters() false: missing url/methodName, proto descriptor not found, or methodName not present in the loaded proto file's service definition.

Common situations: Typo in method name vs the uploaded .proto file; proto file not attached to the task; proto file updated/renamed messages while the task definition still references the old names.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• cannot merge json message to protobuf definition type <messa
• grpc exception: Unrecognized field label:
• dvc task params is not valid
• EMR Serverless task params are not valid
• emr task params is not valid

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