バージョン: 11.x

エラーハンドリング

非公式ベータ版翻訳

このページは PageTurner AI で翻訳されました（ベータ版）。プロジェクト公式の承認はありません。エラーを見つけましたか？問題を報告 →

プロシージャ内でエラーが発生すると、tRPCはクライアントに「error」プロパティを含むオブジェクトを返します。このプロパティにはクライアント側でエラーを処理するために必要な情報が全て含まれています。

不正なリクエスト入力によって発生したエラーレスポンスの例を以下に示します：

json
{
  "id": null,
  "error": {
    "message": "\"password\" must be at least 4 characters",
    "code": -32600,
    "data": {
      "code": "BAD_REQUEST",
      "httpStatus": 400,
      "stack": "...",
      "path": "user.changepassword"
    }
  }
}

json
{
  "id": null,
  "error": {
    "message": "\"password\" must be at least 4 characters",
    "code": -32600,
    "data": {
      "code": "BAD_REQUEST",
      "httpStatus": 400,
      "stack": "...",
      "path": "user.changepassword"
    }
  }
}

本番環境でのスタックトレース

デフォルトでは、tRPCはisDevがtrueの場合にのみerror.data.stackを含めます。 initTRPC.create()はデフォルトでisDevをprocess.env.NODE_ENV !== 'production'に設定します。ランタイム間で一貫した動作が必要な場合は、手動でisDevをオーバーライドしてください。

server.ts
ts
import { initTRPC } from '@trpc/server';
 
const t = initTRPC.create({ isDev: false });

server.ts
ts
import { initTRPC } from '@trpc/server';
 
const t = initTRPC.create({ isDev: false });

返されるエラーフィールドをより厳密に制御する必要がある場合は、エラーフォーマットを使用してください。

エラーコード

tRPCでは、異なる種類のエラーと対応するHTTPステータスコードを表すエラーコードのリストが定義されています。

Code	Description	HTTP code
PARSE_ERROR	Invalid JSON was received by the server, or an error occurred while parsing the request.	400
BAD_REQUEST	The server cannot or will not process the request due to something that is perceived to be a client error.	400
UNAUTHORIZED	The client request has not been completed because it lacks valid authentication credentials for the requested resource.	401
PAYMENT_REQUIRED	The client request requires payment to access the requested resource.	402
FORBIDDEN	The client is not authorized to access the requested resource.	403
NOT_FOUND	The server cannot find the requested resource.	404
METHOD_NOT_SUPPORTED	The server knows the request method, but the target resource doesn't support this method.	405
TIMEOUT	The server would like to shut down this unused connection.	408
CONFLICT	The request conflicts with the current state of the target resource.	409
PRECONDITION_FAILED	Access to the target resource has been denied.	412
PAYLOAD_TOO_LARGE	Request entity is larger than limits defined by server.	413
UNSUPPORTED_MEDIA_TYPE	The server refuses to accept the request because the payload format is in an unsupported format.	415
UNPROCESSABLE_CONTENT	The server understands the request method, and the request entity is correct, but the server was unable to process it.	422
PRECONDITION_REQUIRED	The server cannot process the request because a required precondition header (such as `If-Match`) is missing. When a precondition header does not match the server-side state, the response should be `412 Precondition Failed`.	428
TOO_MANY_REQUESTS	The rate limit has been exceeded or too many requests are being sent to the server.	429
CLIENT_CLOSED_REQUEST	The client closed the connection before the server finished responding.	499
INTERNAL_SERVER_ERROR	An unspecified error occurred.	500
NOT_IMPLEMENTED	The server does not support the functionality required to fulfill the request.	501
BAD_GATEWAY	The server received an invalid response from the upstream server.	502
SERVICE_UNAVAILABLE	The server is not ready to handle the request.	503
GATEWAY_TIMEOUT	The server did not get a response in time from the upstream server that it needed in order to complete the request.	504

tRPCはエラーからHTTPステータスコードを抽出するためのヘルパー関数getHTTPStatusCodeFromErrorを提供しています：

ts
import { getHTTPStatusCodeFromError } from '@trpc/server/http';
 
// Example error you might get if your input validation fails
const error: TRPCError = {
  name: 'TRPCError',
  code: 'BAD_REQUEST',
  message: '"password" must be at least 4 characters',
};
 
if (error instanceof TRPCError) {
  const httpCode = getHTTPStatusCodeFromError(error);
  console.log(httpCode); // 400
}

ts
import { getHTTPStatusCodeFromError } from '@trpc/server/http';
 
// Example error you might get if your input validation fails
const error: TRPCError = {
  name: 'TRPCError',
  code: 'BAD_REQUEST',
  message: '"password" must be at least 4 characters',
};
 
if (error instanceof TRPCError) {
  const httpCode = getHTTPStatusCodeFromError(error);
  console.log(httpCode); // 400
}

ヒント

サーバーサイドコンテキストでのエラーハンドリングの完全な動作例は、Server Side Callsのドキュメントにあります。

エラーのスロー

tRPCはプロシージャ内部で発生したエラーを表現するためのエラーサブクラスTRPCErrorを提供しています。

例えば、次のエラーをスローした場合：

server.ts
ts
import { initTRPC, TRPCError } from '@trpc/server';
 
const t = initTRPC.create();
 
const theError = new Error('something went wrong');
 
const appRouter = t.router({
  hello: t.procedure.query(() => {
    throw new TRPCError({
      code: 'INTERNAL_SERVER_ERROR',
      message: 'An unexpected error occurred, please try again later.',
      // optional: pass the original error to retain stack trace
      cause: theError,
    });
  }),
});
 
// [...]

server.ts
ts
import { initTRPC, TRPCError } from '@trpc/server';
 
const t = initTRPC.create();
 
const theError = new Error('something went wrong');
 
const appRouter = t.router({
  hello: t.procedure.query(() => {
    throw new TRPCError({
      code: 'INTERNAL_SERVER_ERROR',
      message: 'An unexpected error occurred, please try again later.',
      // optional: pass the original error to retain stack trace
      cause: theError,
    });
  }),
});
 
// [...]

結果は次のレスポンスになります：

json
{
  "id": null,
  "error": {
    "message": "An unexpected error occurred, please try again later.",
    "code": -32603,
    "data": {
      "code": "INTERNAL_SERVER_ERROR",
      "httpStatus": 500,
      "stack": "...",
      "path": "hello"
    }
  }
}

json
{
  "id": null,
  "error": {
    "message": "An unexpected error occurred, please try again later.",
    "code": -32603,
    "data": {
      "code": "INTERNAL_SERVER_ERROR",
      "httpStatus": 500,
      "stack": "...",
      "path": "hello"
    }
  }
}

エラーの処理

プロシージャで発生したすべてのエラーは、クライアントに送信される前にonErrorメソッドを通過します。ここでエラーを処理できます（エラーの変更についてはエラーフォーマットを参照）。

server.ts
ts
import { createHTTPServer } from '@trpc/server/adapters/standalone';
import { appRouter } from './router';
 
const server = createHTTPServer({
  router: appRouter,
  onError(opts) {
    const { error, type, path, input, ctx, req } = opts;
    console.error('Error:', error);
    if (error.code === 'INTERNAL_SERVER_ERROR') {
      // send to bug reporting
    }
  },
});

server.ts
ts
import { createHTTPServer } from '@trpc/server/adapters/standalone';
import { appRouter } from './router';
 
const server = createHTTPServer({
  router: appRouter,
  onError(opts) {
    const { error, type, path, input, ctx, req } = opts;
    console.error('Error:', error);
    if (error.code === 'INTERNAL_SERVER_ERROR') {
      // send to bug reporting
    }
  },
});

onErrorパラメータは、エラーとその発生コンテキストに関するすべての情報を含むオブジェクトです：

ts
interface OnErrorOpts {
  error: TRPCError;
  type: 'query' | 'mutation' | 'subscription' | 'unknown';
  path: string | undefined;
  input: unknown;
  ctx: unknown;
  req: Request;
}

ts
interface OnErrorOpts {
  error: TRPCError;
  type: 'query' | 'mutation' | 'subscription' | 'unknown';
  path: string | undefined;
  input: unknown;
  ctx: unknown;
  req: Request;
}

本番環境でのスタックトレース​

エラーコード​

エラーのスロー​

エラーの処理​

本番環境でのスタックトレース

エラーコード

エラーのスロー

エラーの処理