GraphQLを使用していて「Variable "$X" got invalid value; Expected type "Y"」というエラーに遭遇したことはありませんか？このエラーは、GraphQLのクエリやミューテーションに渡す変数の型が、スキーマで定義されている型と一致しない場合に発生します。本記事では、このエラーの原因と具体的な解決方法を詳しく解説します。

エラーの原因

このエラーは主に以下の理由で発生します：

1. 変数の型が間違っている

2. 必須フィールドが欠けている

3. 列挙型の値が正しくない

4. nullが許可されていない箇所でnullを渡している

解決方法

1. 変数の型を確認する

まず、GraphQLのスキーマを確認し、期待される型と実際に渡している値の型が一致しているか確認します。例えば、整数を期待しているところに文字列を渡していないか、などをチェックします。

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

# 変数
{
  "id": 123
}

# 間違った例（文字列を渡している）
{
  "id": "123"
}

2. 必須フィールドを確認する

スキーマで必須とされているフィールドがすべて含まれているか確認します。GraphQLでは、`!`記号が付いているフィールドは必須です。

# スキーマ
type Mutation {
  createUser(input: CreateUserInput!): User
}

input CreateUserInput {
  name: String!
  email: String!
  age: Int
}

# 正しい例
mutation ($input: CreateUserInput!) {
  createUser(input: $input) {
    id
  }
}

# 変数
{
  "input": {
    "name": "John Doe",
    "email": "john@example.com"
  }
}

# 間違った例（必須フィールドの email が欠けている）
{
  "input": {
    "name": "John Doe"
  }
}

3. 列挙型の値を確認する

列挙型を使用している場合、渡す値がスキーマで定義されている値の中から選ばれているか確認します。

# スキーマ
enum UserRole {
  ADMIN
  USER
  GUEST
}

# 正しい例
mutation ($role: UserRole!) {
  setUserRole(role: $role) {
    success
  }
}

# 変数
{
  "role": "ADMIN"
}

# 間違った例（定義されていない値）
{
  "role": "SUPERUSER"
}

4. null値の扱いを確認する

nullが許可されていないフィールドにnullを渡していないか確認します。スキーマで`!`が付いているフィールドはnullを許可しません。

# スキーマ
type Mutation {
  updateUser(id: ID!, name: String!): User
}

# 正しい例
mutation ($id: ID!, $name: String!) {
  updateUser(id: $id, name: $name) {
    id
    name
  }
}

# 変数
{
  "id": "123",
  "name": "John Doe"
}

# 間違った例（name に null を渡している）
{
  "id": "123",
  "name": null
}

まとめ

「Variable "$X" got invalid value; Expected type "Y"」エラーは、主に変数の型の不一致や必須フィールドの欠落によって発生します。このエラーを解決するには、以下の点に注意しましょう：

  • スキーマで定義された型と一致する値を渡す
  • 必須フィールドをすべて含める
  • 列挙型の場合は定義された値のみを使用する
  • nullが許可されていないフィールドにnullを渡さない

これらの点に注意してコードを見直すことで、多くの場合このエラーを解決できます。GraphQLの型システムを正しく理解し、適切に使用することで、より堅牢なアプリケーションを開発することができます。