Module io.jooby.trpc

Package io.jooby.trpc

Class TrpcException

java.lang.Object

java.lang.Throwable

java.lang.Exception

java.lang.RuntimeException

io.jooby.trpc.TrpcException

All Implemented Interfaces:

Serializable

public class TrpcException
extends RuntimeException

A specialized runtime exception that encapsulates a tRPC error.

This exception is thrown when a tRPC procedure fails, either due to framework-level issues (like invalid JSON parsing or missing arguments) or user-thrown domain errors. It holds all the necessary context—the procedure name, the specific TrpcErrorCode, and the underlying cause—required to construct a compliant tRPC error response.

The frontend @trpc/client relies on a very specific JSON envelope to correctly reconstruct the TRPCClientError on the client side. The toMap() method handles translating this Java exception into that exact nested map structure.

See Also:

• Serialized Form

Constructor Summary

Constructors

Constructor	Description
TrpcException(String procedure, io.jooby.StatusCode code)	Constructs a new tRPC exception using a standard Jooby HTTP status code without an underlying cause.
TrpcException(String procedure, io.jooby.StatusCode code, Throwable cause)	Constructs a new tRPC exception using a standard Jooby HTTP status code.
TrpcException(String procedure, TrpcErrorCode code)	Constructs a new tRPC exception without an underlying cause.
TrpcException(String procedure, TrpcErrorCode code, Throwable cause)	Constructs a new tRPC exception using a specific tRPC error code.

Method Summary

Modifier and Type	Method	Description
String	getProcedure()	Gets the name of the tRPC procedure that threw this exception.
io.jooby.StatusCode	getStatusCode()	Gets the HTTP status code associated with this error.
Map<String,Object>	toMap()	Serializes the exception into the exact JSON structure expected by the tRPC protocol.

Methods inherited from class java.lang.Throwable

addSuppressed, fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, getSuppressed, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Details

TrpcException

public TrpcException(String procedure,
 io.jooby.StatusCode code,
 Throwable cause)

Constructs a new tRPC exception using a standard Jooby HTTP status code.

Parameters:

procedure - The name of the tRPC procedure that failed (e.g., "movies.getById").

code - The Jooby HTTP status code, which will be mapped to its closest tRPC equivalent.

cause - The underlying exception that caused this failure.

TrpcException

public TrpcException(String procedure,
 TrpcErrorCode code,
 Throwable cause)

Constructs a new tRPC exception using a specific tRPC error code.

Parameters:

procedure - The name of the tRPC procedure that failed.

code - The explicit tRPC error code.

cause - The underlying exception that caused this failure.

TrpcException

public TrpcException(String procedure,
 TrpcErrorCode code)

Constructs a new tRPC exception without an underlying cause.

Parameters:

procedure - The name of the tRPC procedure that failed.

code - The explicit tRPC error code.

TrpcException

public TrpcException(String procedure,
 io.jooby.StatusCode code)

Constructs a new tRPC exception using a standard Jooby HTTP status code without an underlying cause.

Parameters:

procedure - The name of the tRPC procedure that failed.

code - The Jooby HTTP status code.

Method Details

getStatusCode

public io.jooby.StatusCode getStatusCode()

Gets the HTTP status code associated with this error.

Returns:

The Jooby StatusCode to be set in the HTTP response headers.

getProcedure

public String getProcedure()

Gets the name of the tRPC procedure that threw this exception.

Returns:

The procedure name (e.g., "movies.getById").

toMap

public Map<String,Object> toMap()

Serializes the exception into the exact JSON structure expected by the tRPC protocol.

The resulting map translates into the following JSON shape:

 {
 "error": {
 "message": "The descriptive error message",
 "code": -32600,
 "data": {
 "code": "BAD_REQUEST",
 "httpStatus": 400,
 "path": "movies.getById"
 }
 }
 }
 

Returns:

A nested map representing the JSON error envelope.