GraphQLで「Undefined variable "$X"」エラーが表示されたときの解決方法

GraphQLを使用していると、時折「Undefined variable "$X"」というエラーに遭遇することがあります。このエラーは、クエリやミューテーションで使用している変数が適切に定義されていない場合に発生します。本記事では、このエラーの原因と解決方法について詳しく説明します。

エラーの原因

「Undefined variable "$X"」エラーの主な原因は以下の3つです：

1. 変数の宣言漏れ

2. 変数名のタイプミス

3. 変数の型定義の不備

解決方法

1. 変数の宣言を確認する

まず、クエリやミューテーションの冒頭で変数が正しく宣言されているか確認しましょう。変数の宣言は以下のような形式で行います：

query GetUser($userId: ID!) {
  user(id: $userId) {
    name
    email
  }
}

この例では、`$userId`という変数が宣言されています。

2. 変数名のスペルを確認する

変数名のタイプミスがないか、慎重にチェックしてください。大文字小文字の違いも重要です。

# 正しい例
query GetUser($userId: ID!) {
  user(id: $userId) {
    name
  }
}

# 間違った例（変数名が異なる）
query GetUser($userId: ID!) {
  user(id: $userID) {
    name
  }
}

3. 変数の型を確認する

変数の型が正しく定義されているか確認しましょう。必須の変数には`!`を付ける必要があります。

# 正しい例（必須の場合）
query GetUser($userId: ID!) {
  user(id: $userId) {
    name
  }
}

# 正しい例（オプションの場合）
query GetUser($userId: ID) {
  user(id: $userId) {
    name
  }
}

4. クライアント側での変数の受け渡しを確認する

フロントエンドのコードで、変数が正しくGraphQLクエリに渡されているか確認してください。

// React + Apollo Clientの例
const GET_USER = gql`
  query GetUser($userId: ID!) {
    user(id: $userId) {
      name
      email
    }
  }
`;

function UserProfile({ userId }) {
  const { loading, error, data } = useQuery(GET_USER, {
    variables: { userId },
  });
  // ...
}

5. サーバー側の実装を確認する

サーバー側でリゾルバーが正しく実装されているか確認してください。変数の名前や型が、スキーマ定義と一致している必要があります。

// Node.js + Apollo Serverの例
const resolvers = {
  Query: {
    user: (_, { id }) => {
      // idを使用してユーザーを取得する処理
    },
  },
};

まとめ

「Undefined variable "$X"」エラーは、主に変数の宣言や使用方法に問題がある場合に発生します。変数の宣言、名前のスペル、型定義を慎重にチェックし、クライアント側とサーバー側の実装を確認することで、このエラーを解決できます。GraphQLの正しい使用方法を理解し、適切なデバッグ手法を身につけることで、より効率的な開発が可能になります。