--- schema_version: "1" id: ddd30cc7e996d2a603a9d346d1fe19ce44bff617ab6367f7b5caf3d2695edd74 title: APIkit for gRPC Module Reference collection: mulesoft version: current locale: en-us portal_url: https://docs.salesforce.com/mulesoft/current/en-us/apikit/latest/apikit-for-grpc-module-reference.md canonical_url: https://docs.mulesoft.com/apikit/latest/apikit-for-grpc-module-reference source_site: docs.mulesoft.com content_type: documentation content_hash: e313019381ec682e00b14896c5b9d027ca10f706f3c18a8f5266dadaaab804ed description: MuleSoft Documentation Site release: 4.x latest: true --- # APIkit for gRPC Module Reference Implement gRPC APIs in Mule applications with APIkit for gRPC: declare dependencies, namespaces, and configuration elements that wire Protocol Buffer (`.proto`) services into flows. This reference lists Maven coordinates, XML schema locations, `grpc:config`, operations, and sources you use when you scaffold or customize gRPC endpoints. ## [](#dependencies)Dependencies Add the gRPC Connector (server) dependency to your Mule project: ```xml com.mulesoft.connectors mule-grpc-connector LATEST_VERSION (1) mule-plugin ```

1	To get the LATEST_VERSION, check the APIkit Release Notes .

## [](#namespace-and-schema)Namespace and Schema Use this namespace and schema location in your Mule configuration: ```xml xmlns:grpc="http://www.mulesoft.org/schema/mule/grpc" xsi:schemaLocation="http://www.mulesoft.org/schema/mule/grpc http://www.mulesoft.org/schema/mule/grpc/current/mule-grpc.xsd" ``` ## [](#configurations)Configurations ### [](#grpc-server-config)grpc:server-config Configures the gRPC server that listens for incoming gRPC requests. This element wraps the connection provider, which defines the listening endpoint and the Interface Description Language (IDL) definition that describes the service and message types. #### [](#parameters)Parameters

Name Type Description Default Value Required

Name	Type	Description	Default Value	Required
`Name`	String	Identifier of this element used to reference it in other components.	None	Yes
`maxInboundMessageSize`	Number	Maximum size in bytes for inbound gRPC messages. Messages exceeding this size are rejected.	4194304 (4 MB)	No

Name

String

Identifier of this element used to reference it in other components.

None

Yes

maxInboundMessageSize

Number

Maximum size in bytes for inbound gRPC messages. Messages exceeding this size are rejected.

4194304 (4 MB)

#### [](#example)Example ```xml

``` #### [](#associated-operations)Associated Operations - [grpc:send-stream-message](#send-stream-message) - [grpc:end-stream](#end-stream) #### [](#associated-sources)Associated Sources - [Unary Method](#unary-method) - [Client Streaming Method](#client-streaming-method) - [Server Streaming Method](#server-streaming-method) - [Bidirectional Streaming Method](#bidirectional-streaming-method) ### [](#grpc-server-connection)grpc:grpc-server-connection Connection provider for the gRPC server. The gRPC server doesn’t independently configure host, port, or TLS; it uses an existing HTTP listener. This connection references an `http:listener-config` for the listening endpoint and defines the protobuf descriptor (IDL) that describes the service and message types. #### [](#parameters-2)Parameters

Parameter Type Description Default Value Required

Parameter	Type	Description	Default Value	Required
`listenerConfig`	ConfigReference to `http:listener-config`	Reference to the HTTP listener configuration that defines host, port, and TLS. The gRPC server uses this listener for transport.	None	Yes

listenerConfig

ConfigReference to http:listener-config

Reference to the HTTP listener configuration that defines host, port, and TLS. The gRPC server uses this listener for transport.

None

Yes

#### [](#child-elements)Child Elements ##### [](#grpcidl-definition)grpc:idl-definition Contains the protobuf descriptor (IDL) for the gRPC service. The `grpc:single-binary-protobuf` definition is supported. ##### [](#grpcsingle-binary-protobuf)grpc:single-binary-protobuf Provides the Protocol Buffer descriptor from a binary file (for example, a compiled `.proto` descriptor file).

Parameter Type Description Default Value Required

Parameter	Type	Description	Default Value	Required
`protobufDescriptorFile`	String	Path or expression (for example, `${grpc.server.descriptor.file}`) that resolves to the binary Protobuf descriptor file.	None	Yes

protobufDescriptorFile

String

Path or expression (for example, ${grpc.server.descriptor.file}) that resolves to the binary Protobuf descriptor file.

None

Yes

## [](#operations)Operations ### [](#send-stream-message)grpc:send-stream-message Sends a message on an active server streaming response. To push messages to the client, use this operation within a flow triggered by `grpc:server-streaming-method`. This operation doesn’t support bidirectional streaming. #### [](#parameters-3)Parameters

Parameter Type Description Default Value Required

Parameter	Type	Description	Default Value	Required
`config-ref`	String (Config Reference)	Reference to the grpc:server-config to use.	None	Yes
`Payload`	Any	The message payload to send. It should conform to the message type defined in the Interface Description Language (IDL) for the streaming method.	#[payload]	No
`Target Variable`	String	Name of a variable on which the operation output is placed.	None	No
`Target Value`	String	Expression evaluated against the operation output. The result is stored in the target variable.	#[payload]	No

config-ref

String (Config Reference)

Reference to the grpc:server-config to use.

None

Yes

Payload

Any

The message payload to send. It should conform to the message type defined in the Interface Description Language (IDL) for the streaming method.

#[payload]

Target Variable

String

Name of a variable on which the operation output is placed.

None

Target Value

String

Expression evaluated against the operation output. The result is stored in the target variable.

#[payload]

#### [](#configurations-2)Configurations - [grpc:server-config](#grpc-server-config) ### [](#end-stream)grpc:end-stream Ends the current server stream. Call this operation after sending all messages to the client. This operation doesn’t support bidirectional streaming. #### [](#parameters-4)Parameters

Parameter Type Description Default Value Required

Parameter	Type	Description	Default Value	Required
`config-ref`	String (Config Reference)	Reference to the grpc:server-config to use.	None	Yes
`Target Variable`	String	Name of a variable on which the operation output is placed.	None	No
`Target Value`	String	Expression evaluated against the operation output. The result is stored in the target variable.	#[payload]	No

config-ref

String (Config Reference)

Reference to the grpc:server-config to use.

None

Yes

Target Variable

String

Name of a variable on which the operation output is placed.

None

Target Value

String

Expression evaluated against the operation output. The result is stored in the target variable.

#[payload]

#### [](#configurations-3)Configurations - [grpc:server-config](#grpc-server-config) ## [](#sources-listeners)Sources (Listeners) ### [](#unary-method)Unary Method `` Handles unary RPCs: one request from the client and one response from the server. #### [](#parameters-5)Parameters

Parameter Type Description Default Value Required

Parameter	Type	Description	Default Value	Required
`config-ref`	String (Config Reference)	Reference to the grpc:server-config to use.	None	Yes
`methodName`	String	Fully qualified method name in the format `ServiceName/MethodName` (for example, `com.example.MyService/MyMethod`).	None	Yes
`Primary Node Only`	Boolean	Whether this source runs only on the primary node in a cluster.	false	No
`Redelivery Policy`	Object	Policy for redelivery of the same message.	None	No

config-ref

String (Config Reference)

Reference to the grpc:server-config to use.

None

Yes

methodName

String

Fully qualified method name in the format ServiceName/MethodName (for example, com.example.MyService/MyMethod).

None

Yes

Primary Node Only

Boolean

Whether this source runs only on the primary node in a cluster.

false

Redelivery Policy

Object

Policy for redelivery of the same message.

None

#### [](#output)Output

Type

Any (message type from IDL)

#### [](#configurations-4)Configurations - [grpc:server-config](#grpc-server-config) ### [](#client-streaming-method)Client Streaming Method `` Handles client streaming RPCs: the client sends a stream of messages and the server responds with a single message. #### [](#parameters-6)Parameters

Parameter Type Description Default Value Required

Parameter	Type	Description	Default Value	Required
`config-ref`	String (Config Reference)	Reference to the grpc:server-config to use.	None	Yes
`methodName`	String	Fully qualified method name in the format `ServiceName/MethodName` (for example, `com.example.MyService/MyMethod`).	None	Yes
`Primary Node Only`	Boolean	Whether this source runs only on the primary node in a cluster.	false	No
`Redelivery Policy`	Object	Policy for redelivery of the same message.	None	No

config-ref

String (Config Reference)

Reference to the grpc:server-config to use.

None

Yes

methodName

String

Fully qualified method name in the format ServiceName/MethodName (for example, com.example.MyService/MyMethod).

None

Yes

Primary Node Only

Boolean

Whether this source runs only on the primary node in a cluster.

false

Redelivery Policy

Object

Policy for redelivery of the same message.

None

#### [](#child-elements-2)Child Elements ##### [](#grpcoutput)grpc:output Optional nested element that defines the response and stream state for the client streaming method. Only `grpc:client-streaming-method` has this element. Unary and server streaming don’t use this element.

Parameter Type Description Default Value Required

Parameter	Type	Description	Default Value	Required
`response`	TypedValue<InputStream>	Response payload. Only effective on the final flow execution when `attributes.streamCompleted` is true.	#[payload]	No
`streamState`	Map<String, Object>	State persisted across messages via `attributes.streamState`.	#[{}]	No

response

TypedValue<InputStream>

Response payload. Only effective on the final flow execution when attributes.streamCompleted is true.

#[payload]

streamState

Map<String, Object>

State persisted across messages via attributes.streamState.

#[{}]

Specify stream state in two ways: - **Attribute form** (expression): `streamState="#[vars.myState]"`. - **Nested element form** (often generated by the scaffolder): use `grpc:stream-states` with one or more `grpc:stream-state` children, each with `key` and `value` attributes. ```xml

``` #### [](#output-2)Output

Type

Stream of Any (message type from IDL)

#### [](#configurations-5)Configurations - [grpc:server-config](#grpc-server-config) ### [](#server-streaming-method)Server Streaming Method `` Handles server streaming RPCs: the client sends one request and the server responds with a stream of messages. Use `grpc:send-stream-message` and `grpc:end-stream` within the flow to send messages and close the stream. #### [](#parameters-7)Parameters

Parameter Type Description Default Value Required

Parameter	Type	Description	Default Value	Required
`config-ref`	String (Config Reference)	Reference to the grpc:server-config to use.	None	Yes
`methodName`	String	Fully qualified method name in the format `ServiceName/MethodName` (for example, `com.example.MyService/MyMethod`).	None	Yes
`onCapacityOverload`	Enum: WAIT, DROP	Backpressure strategy when the flow’s `maxConcurrency` is reached. See Backpressure Strategy.	WAIT	No
`Primary Node Only`	Boolean	Whether this source runs only on the primary node in a cluster.	false	No
`Redelivery Policy`	Object	Policy for redelivery of the same message.	None	No

config-ref

String (Config Reference)

Reference to the grpc:server-config to use.

None

Yes

methodName

String

Fully qualified method name in the format ServiceName/MethodName (for example, com.example.MyService/MyMethod).

None

Yes

onCapacityOverload

Enum: WAIT, DROP

Backpressure strategy when the flow’s maxConcurrency is reached. See Backpressure Strategy.

WAIT

Primary Node Only

Boolean

Whether this source runs only on the primary node in a cluster.

false

Redelivery Policy

Object

Policy for redelivery of the same message.

None

#### [](#output-3)Output

Type

Any (request message type from IDL); response is sent via grpc:send-stream-message and grpc:end-stream

#### [](#configurations-6)Configurations - [grpc:server-config](#grpc-server-config) ### [](#bidirectional-streaming-method)Bidirectional Streaming Method `` Handles bidirectional streaming RPCs: both client and server send streams of messages independently. The operations `grpc:send-stream-message` and `grpc:end-stream` don’t support bidirectional streaming. Use the nested `grpc:stream-output` child element to send inline response messages. #### [](#parameters-8)Parameters

Parameter Type Description Default Value Required

Parameter	Type	Description	Default Value	Required
`config-ref`	String (Config Reference)	Reference to the grpc:server-config to use.	None	Yes
`methodName`	String	Fully qualified method name in the format `ServiceName/MethodName` (for example, `com.example.MyService/MyMethod`).	None	Yes
`Primary Node Only`	Boolean	Whether this source runs only on the primary node in a cluster.	false	No
`Redelivery Policy`	Object	Policy for redelivery of the same message.	None	No

config-ref

String (Config Reference)

Reference to the grpc:server-config to use.

None

Yes

methodName

String

Fully qualified method name in the format ServiceName/MethodName (for example, com.example.MyService/MyMethod).

None

Yes

Primary Node Only

Boolean

Whether this source runs only on the primary node in a cluster.

false

Redelivery Policy

Object

Policy for redelivery of the same message.

None

#### [](#child-elements-3)Child Elements ##### [](#grpcstream-output)grpc:stream-output Optional nested element that defines the response and stream state for the bidirectional streaming method. Use it to send inline response messages to the client.

Parameter Type Description Default Value Required

Parameter	Type	Description	Default Value	Required
`response`	TypedValue<InputStream>	Response payload sent to the client.	#[payload]	No
`streamState`	Map<String, Object>	State persisted across messages via `attributes.streamState`.	#[{}]	No

response

TypedValue<InputStream>

Response payload sent to the client.

#[payload]

streamState

Map<String, Object>

State persisted across messages via attributes.streamState.

#[{}]

Specify stream state in two ways. **Attribute form**: `streamState="[vars.state]"`. **Nested element form**: use `grpc:stream-states` with `grpc:stream-state` children (each with `key` and `value` attributes), for example ``. #### [](#output-4)Output

Type

Stream of Any (message type from IDL). Send response messages using the nested grpc:stream-output element.

#### [](#configurations-7)Configurations - [grpc:server-config](#grpc-server-config) ## [](#backpressure-strategy)Backpressure Strategy The gRPC connector uses Mule’s built-in backpressure mechanism. To define how many requests can be processed concurrently, set `maxConcurrency` on the `` element (for example, ``). When that limit is reached, the source applies a backpressure strategy to new incoming requests. The connector does not implement its own concurrency limit. Instead it responds to Mule runtime’s concurrency control. For more information, see [Back-Pressure and MaxConcurrency](https://docs.mulesoft.com/mule-runtime/latest/tuning-backpressure-maxconcurrency). - **onCapacityOverload** (server streaming only): For `grpc:server-streaming-method`, the `onCapacityOverload` attribute chooses the behavior when the flow’s maxConcurrency is reached. Other sources use a fixed mode (see table below). - **WAIT**: New requests wait until a concurrency slot becomes available. The request is eventually processed. - **DROP**: New requests are rejected immediately. The client receives gRPC status `RESOURCE_EXHAUSTED` (8). - **FAIL**: New requests are rejected immediately. The client receives gRPC status `UNAVAILABLE` (14). This is the only mode for unary.

Source Default Mode Supported Modes Notes

Source	Default Mode	Supported Modes	Notes
`grpc:unary-method`	FAIL	FAIL	Excess requests are immediately rejected with `UNAVAILABLE`.
`grpc:server-streaming-method`	WAIT	WAIT, DROP	Configurable via `onCapacityOverload` attribute on the source (default WAIT).
`grpc:client-streaming-method`	WAIT	WAIT	Incoming messages queue until a slot is available.
`grpc:bidirectional-streaming-method`	WAIT	WAIT	Incoming messages queue until a slot is available.

grpc:unary-method

FAIL

Excess requests are immediately rejected with UNAVAILABLE.

grpc:server-streaming-method

WAIT

WAIT, DROP

Configurable via onCapacityOverload attribute on the source (default WAIT).

grpc:client-streaming-method

WAIT

Incoming messages queue until a slot is available.

grpc:bidirectional-streaming-method

WAIT

Incoming messages queue until a slot is available.

## [](#error-handling)Error Handling gRPC uses status code 0 (OK) for successful responses. This is not an error type. The following sections describe error conditions (status codes 1–16) and how they map to Mule error types. ### [](#error-type-hierarchy)Error Type Hierarchy All gRPC protocol errors extend the base type `GRPC:GRPC_ERROR`. In error handlers, reference `GRPC:GRPC_ERROR` to catch any gRPC protocol error, or reference a specific type for finer-grained handling. ### [](#grpc-protocol-errors)gRPC Protocol Errors The Mule error types in this table map to gRPC status codes. These errors extend `GRPC:GRPC_ERROR`.

Mule Error Type	gRPC Code	Description
GRPC:CANCELLED	1	Request was cancelled
GRPC:GRPC_UNKNOWN	2	Unknown error
GRPC:INVALID_ARGUMENT	3	Invalid argument
GRPC:DEADLINE_EXCEEDED	4	Deadline exceeded
GRPC:NOT_FOUND	5	Resource not found
GRPC:ALREADY_EXISTS	6	Resource exists
GRPC:PERMISSION_DENIED	7	Permission denied
GRPC:RESOURCE_EXHAUSTED	8	Resource exhausted
GRPC:FAILED_PRECONDITION	9	Failed precondition
GRPC:ABORTED	10	Operation aborted
GRPC:OUT_OF_RANGE	11	Argument out of range
GRPC:UNIMPLEMENTED	12	Operation not implemented
GRPC:INTERNAL	13	Internal error
GRPC:UNAVAILABLE	14	Service unavailable
GRPC:DATA_LOSS	15	Data loss
GRPC:UNAUTHENTICATED	16	Request not authenticated

Mule Error Type

gRPC Code

Description

GRPC:CANCELLED

Request was cancelled

GRPC:GRPC_UNKNOWN

Unknown error

GRPC:INVALID_ARGUMENT

Invalid argument

GRPC:DEADLINE_EXCEEDED

Deadline exceeded

GRPC:NOT_FOUND

Resource not found

GRPC:ALREADY_EXISTS

Resource exists

GRPC:PERMISSION_DENIED

Permission denied

GRPC:RESOURCE_EXHAUSTED

Resource exhausted

GRPC:FAILED_PRECONDITION

Failed precondition

GRPC:ABORTED

Operation aborted

GRPC:OUT_OF_RANGE

Argument out of range

GRPC:UNIMPLEMENTED

Operation not implemented

GRPC:INTERNAL

Internal error

GRPC:UNAVAILABLE

Service unavailable

GRPC:DATA_LOSS

Data loss

GRPC:UNAUTHENTICATED

Request not authenticated

### [](#connector-level-errors)Connector-Level Errors The error types in this table are thrown by the connector for validation, transformation, and connectivity issues. They’re not gRPC protocol status codes but Mule error types used by the gRPC connector.

Error Type	Description
GRPC:VALIDATION	Thrown after request or message validation fails (for example, schema or IDL validation).
GRPC:TRANSFORMATION	Thrown after message transformation fails (for example, serialization or deserialization of Protobuf messages).
GRPC:CONNECTIVITY	Thrown after a connectivity issue occurs (for example, connection refused or transport error).

Error Type

Description

GRPC:VALIDATION

Thrown after request or message validation fails (for example, schema or IDL validation).

GRPC:TRANSFORMATION

Thrown after message transformation fails (for example, serialization or deserialization of Protobuf messages).

GRPC:CONNECTIVITY

Thrown after a connectivity issue occurs (for example, connection refused or transport error).

## [](#see-also)See Also - [APIkit for gRPC](https://docs.mulesoft.com/apikit/latest/apikit-for-grpc) - [gRPC Support on Anypoint Platform](https://docs.mulesoft.com/release-notes/platform/grpc-support) - [Implementing a gRPC API Specification with Anypoint Code Builder](https://docs.mulesoft.com/anypoint-code-builder/imp-implement-grpc-api-spec)