---
title: VGPUError
description: `VGPUError` is the structured error base class used by vgpu. Use it when you need stable machine-readable `code`, `severity`, optional `fix`, `where`, and `cause` fields instead of parsing error messages.
---

# VGPUError



## Import

```ts
import { VGPUError, ValidationError } from "vgpu/core";
```

## Signature

```ts
type VGPUErrorSeverity = "error" | "warning" | "info";

interface VGPUErrorData {
  readonly code: string;
  readonly message: string;
  readonly severity?: VGPUErrorSeverity;
  readonly fix?: string;
  readonly where?: string;
  readonly cause?: unknown;
}

declare class VGPUError extends Error {
  readonly code: string;
  readonly severity: VGPUErrorSeverity;
  readonly fix?: string;
  readonly where?: string;
  readonly cause?: unknown;
  constructor(data: VGPUErrorData);
}

declare class ValidationError extends VGPUError {
  constructor(data: Omit<VGPUErrorData, "severity">);
}
```

## Parameters

### `new VGPUError(data)`

| Param         | Type                             | Required | Default     | Notes                                                                        |
| ------------- | -------------------------------- | -------: | ----------- | ---------------------------------------------------------------------------- |
| data.code     | `string`                         |        ✔ | —           | Stable machine-readable code. Core validation sites use `VGPU-CORE-*` codes. |
| data.message  | `string`                         |        ✔ | —           | Human-readable message passed to `Error`.                                    |
| data.severity | `"error" \| "warning" \| "info"` |        ✖ | `"error"`   | Stored as `.severity`; omitted data becomes an error.                        |
| data.fix      | `string`                         |        ✖ | `undefined` | Optional remediation text.                                                   |
| data.where    | `string`                         |        ✖ | `undefined` | Optional source/context label such as `"Device.createBuffer"`.               |
| data.cause    | `unknown`                        |        ✖ | `undefined` | Forwarded to `Error` via `{ cause }` and stored as `.cause`.                 |

### `new ValidationError(data)`

| Param        | Type      | Required | Default     | Notes                                         |
| ------------ | --------- | -------: | ----------- | --------------------------------------------- |
| data.code    | `string`  |        ✔ | —           | Stable machine-readable validation code.      |
| data.message | `string`  |        ✔ | —           | Human-readable validation message.            |
| data.fix     | `string`  |        ✖ | `undefined` | Optional remediation text.                    |
| data.where   | `string`  |        ✖ | `undefined` | Optional source/context label.                |
| data.cause   | `unknown` |        ✖ | `undefined` | Optional original error or validation detail. |

**Returns:**

* `new VGPUError(data)` returns an `Error` instance with `.name === "VGPUError"`, `.code`, `.severity`, optional `.fix`, optional `.where`, and optional `.cause`.
* `new ValidationError(data)` returns a `VGPUError` subclass with `.name === "ValidationError"` and `.severity === "error"`.

**Throws:** Constructors do not throw vgpu errors. They can only throw if the JavaScript runtime cannot construct `Error` or assign fields.

## Examples

```ts
import { VGPUError } from "vgpu/core";

const error = new VGPUError({
  code: "VGPU-CORE-INVALID-USAGE",
  message: "Buffer size must be greater than zero.",
  severity: "error",
  where: "Device.createBuffer",
  fix: "Pass a positive byte length.",
});

console.log(error.name, error.code, error.severity, error.where);
```

```ts
import { ValidationError } from "vgpu/core";

function requirePositive(value: number): void {
  if (value <= 0) {
    throw new ValidationError({
      code: "VGPU-CORE-INVALID-USAGE",
      message: "Expected a positive value.",
      where: "example.requirePositive",
    });
  }
}

try {
  requirePositive(0);
} catch (error) {
  if (error instanceof ValidationError) {
    console.log(error.code); // "VGPU-CORE-INVALID-USAGE"
  }
}
```

```ts
import { createMockAdapter } from "vgpu/mock";
import { VGPUError } from "vgpu/core";

const device = await createMockAdapter().requestDevice();

device.pushErrorScope("validation");
device.createBuffer({ size: 0, usage: ["copy_dst"] });
const error = await device.popErrorScope();

if (error instanceof VGPUError) {
  console.log(error.code); // "VGPU-CORE-INVALID-USAGE"
}

device.destroy();
```

## Notes

* Match on `.code`, not `.message`. Messages can become more descriptive; codes are the stable contract.
* `ValidationError` forces severity to `"error"`; use `VGPUError` directly for `"warning"` or `"info"` severities.
* Core currently emits these `VGPU-CORE-*` codes from core layer (`vgpu/core`) code paths: `VGPU-CORE-INVALID-USAGE`, `VGPU-CORE-VALIDATION`, `VGPU-CORE-EXTERNAL-TEXTURE`, `VGPU-CORE-TEXTURE-RESIZE-LOCKED`, `VGPU-CORE-TEXTURE-DESTROYED`, `VGPU-CORE-UNSUPPORTED-FORMAT`, `VGPU-CORE-BIND-GROUP-LAYOUT-REQUIRED`, `VGPU-CORE-SAMPLER-ANISOTROPY-FILTERS`, `VGPU-CORE-BINDING-INVALID`, and `VGPU-CORE-VISIBILITY-INVALID`.
* Native WebGPU errors are converted to `VGPU-CORE-VALIDATION` only by `Device.popErrorScope()`; other native calls may still throw native errors directly.
* **See also:** `Device`, `Buffer`, `Texture`, `bind`, `VGPUAdapter`.


---

For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md)

For an index of all available documentation, see [/llms.txt](/llms.txt)

For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)