# GraphQL Error

> GraphQL error and response types with locations, path, and extensions.

- Name: `graphql-error`
- Categories: api
- Detail page: https://open-types.dev/types/graphql-error

## Install

```bash
# Types only
npx shadcn add @open-types/graphql-error

# Types + Zod v4 validators
npx shadcn add @open-types/graphql-error-zod

# Types + real-world examples
npx shadcn add @open-types/graphql-error-examples
```

## Types

```typescript
export interface GraphQLErrorLocation {
  line: number;
  column: number;
}

export interface GraphQLError {
  message: string;
  locations?: GraphQLErrorLocation[];
  path?: (string | number)[];
  extensions?: Record<string, unknown>;
}

export interface GraphQLResponse {
  data?: Record<string, unknown> | null;
  errors?: GraphQLError[];
}
```

## Zod validator

```typescript
import * as z from "zod";
import type {
  GraphQLError,
  GraphQLErrorLocation,
  GraphQLResponse,
} from "../types/graphql-error";

export const graphQLErrorLocationSchema = z.object({
  line: z.number().int().min(1, { error: "Line must be at least 1" }),
  column: z.number().int().min(1, { error: "Column must be at least 1" }),
}) satisfies z.ZodType<GraphQLErrorLocation>;

export const graphQLErrorSchema = z.object({
  message: z.string().min(1, { error: "Error message is required" }),
  locations: z.array(graphQLErrorLocationSchema).optional(),
  path: z.array(z.union([z.string(), z.number()])).optional(),
  extensions: z.record(z.string(), z.unknown()).optional(),
}) satisfies z.ZodType<GraphQLError>;

export const graphQLResponseSchema = z.object({
  data: z.record(z.string(), z.unknown()).nullable().optional(),
  errors: z.array(graphQLErrorSchema).optional(),
}) satisfies z.ZodType<GraphQLResponse>;

export type {
  GraphQLError,
  GraphQLErrorLocation,
  GraphQLResponse,
} from "../types/graphql-error";
```

## Examples

```typescript
// Source: https://spec.graphql.org/October2021/#sec-Errors
// Captured: 2026-05
import type {
  GraphQLErrorLocation,
  GraphQLError,
  GraphQLResponse,
} from "../types/graphql-error";

const location = { line: 4, column: 3 } as const satisfies GraphQLErrorLocation;

export const graphQLErrorLocationExamples = {
  topLevel: { line: 1, column: 1 } satisfies GraphQLErrorLocation,
  nested: location,
  deep: { line: 42, column: 18 } satisfies GraphQLErrorLocation,
} as const;

const fieldError = {
  message: "Cannot return null for non-nullable field User.email",
  locations: [location],
  path: ["user", "email"],
  extensions: { code: "INTERNAL_SERVER_ERROR" },
} as const satisfies GraphQLError;

export const graphQLErrorExamples = {
  fieldError,
  syntax: {
    message: 'Syntax Error: Unexpected token "}"',
    locations: [{ line: 6, column: 1 }],
  } satisfies GraphQLError,
  unauthorized: {
    message: "Unauthorized",
    path: ["createOrder"],
    extensions: { code: "UNAUTHENTICATED", classification: "AuthenticationError" },
  } satisfies GraphQLError,
  arrayPath: {
    message: "Item validation failed",
    path: ["orders", 2, "items", 0, "quantity"],
    extensions: { code: "BAD_USER_INPUT" },
  } satisfies GraphQLError,
} as const;

export const graphQLResponseExamples = {
  errorOnly: { errors: [fieldError] } satisfies GraphQLResponse,
  partial: {
    data: { user: { id: "user_321", name: "Jenny Rosen", email: null } },
    errors: [fieldError],
  } satisfies GraphQLResponse,
  success: {
    data: { user: { id: "user_321", name: "Jenny Rosen" } },
  } satisfies GraphQLResponse,
  nullData: { data: null, errors: [fieldError] } satisfies GraphQLResponse,
  empty: {} satisfies GraphQLResponse,
} as const;
```