0
# @pnpm/error
1

2
@pnpm/error provides specialized error classes for pnpm package manager operations. It offers typed error handling for general pnpm errors, HTTP fetch failures, and lockfile inconsistency issues with built-in support for error code standardization and authentication token masking.
3

4
## Package Information
5

6
- **Package Name**: @pnpm/error
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @pnpm/error`
10

11
## Core Imports
12

13
```typescript
14
import { PnpmError, FetchError, LockfileMissingDependencyError } from "@pnpm/error";
15
import type { FetchErrorResponse, FetchErrorRequest } from "@pnpm/error";
16
```
17

18
For CommonJS:
19

20
```javascript
21
const { PnpmError, FetchError, LockfileMissingDependencyError } = require("@pnpm/error");
22
```
23

24
## Basic Usage
25

26
```typescript
27
import { PnpmError, FetchError, LockfileMissingDependencyError } from "@pnpm/error";
28

29
// General pnpm error
30
try {
31
  throw new PnpmError("THE_ERROR_CODE", "Something went wrong", {
32
    hint: "Try running with --verbose for more details"
33
  });
34
} catch (err) {
35
  console.log(err.code); // "ERR_PNPM_THE_ERROR_CODE"
36
  console.log(err.message); // "Something went wrong"
37
  console.log(err.hint); // "Try running with --verbose for more details"
38
}
39

40
// HTTP fetch error
41
const fetchError = new FetchError(
42
  { url: "https://registry.npmjs.org/some-package" },
43
  { status: 404, statusText: "Not Found" }
44
);
45

46
// Lockfile dependency error
47
const lockfileError = new LockfileMissingDependencyError("some-dep@1.0.0");
48
```
49

50
## Capabilities
51

52
### Base Error Class
53

54
Core error class for all pnpm-related errors with automatic error code prefixing and optional hints.
55

56
```typescript { .api }
57
class PnpmError extends Error {
58
  /** Error code, automatically prefixed with 'ERR_PNPM_' if not already present */
59
  readonly code: string;
60
  /** Optional hint for resolving the error */
61
  readonly hint?: string;
62
  /** Number of attempts made before the error occurred */
63
  attempts?: number;
64
  /** Prefix associated with the error context */
65
  prefix?: string;
66
  /** Stack of packages associated with the error */
67
  pkgsStack?: Array<{ id: string, name: string, version: string }>;
68

69
  constructor(
70
    code: string,
71
    message: string,
72
    opts?: {
73
      attempts?: number;
74
      hint?: string;
75
    }
76
  );
77
}
78
```
79

80
### HTTP Fetch Error Handling
81

82
Specialized error class for HTTP request failures with automatic authentication token masking for security.
83

84
```typescript { .api }
85
class FetchError extends PnpmError {
86
  /** Response information from the failed HTTP request */
87
  readonly response: FetchErrorResponse;
88
  /** Request information with authentication details masked for security */
89
  readonly request: FetchErrorRequest;
90

91
  /**
92
   * Creates a fetch error with automatic authentication token masking
93
   * @param request - Request details including URL and optional auth header
94
   * @param response - Response details with status code and message
95
   * @param hint - Optional additional hint for error resolution
96
   * @remarks The constructor automatically masks auth tokens in the request object for security
97
   */
98
  constructor(
99
    request: FetchErrorRequest,
100
    response: FetchErrorResponse,
101
    hint?: string
102
  );
103
}
104
```
105

106
### Lockfile Dependency Errors
107

108
Error class for lockfile inconsistency issues with built-in resolution hints.
109

110
```typescript { .api }
111
class LockfileMissingDependencyError extends PnpmError {
112
  /**
113
   * Creates an error for missing lockfile dependencies with automatic hint
114
   * @param depPath - The dependency path that is missing from the lockfile
115
   * @remarks Uses WANTED_LOCKFILE constant from @pnpm/constants to reference the lockfile name
116
   */
117
  constructor(depPath: string);
118
}
119
```
120

121
## Types
122

123
```typescript { .api }
124
interface FetchErrorResponse {
125
  /** HTTP status code from the failed request */
126
  status: number;
127
  /** HTTP status text from the failed request */
128
  statusText: string;
129
}
130

131
interface FetchErrorRequest {
132
  /** The URL that was being requested */
133
  url: string;
134
  /** Optional authorization header value (will be masked in error output) */
135
  authHeaderValue?: string;
136
}
137
```
138

139
## Error Code Standardization
140

141
All PnpmError instances automatically standardize error codes:
142
- Codes are prefixed with "ERR_PNPM_" if not already present
143
- FetchError uses codes like "ERR_PNPM_FETCH_404", "ERR_PNPM_FETCH_401"
144
- LockfileMissingDependencyError uses "ERR_PNPM_LOCKFILE_MISSING_DEPENDENCY"
145

146
## Security Features
147

148
FetchError automatically masks authentication information in error messages and request objects:
149
- Long tokens (≥20 characters): Shows first 4 characters + "[hidden]" (e.g., "Bearer 1234[hidden]")
150
- Short tokens (<20 characters): Shows auth type + "[hidden]" (e.g., "Bearer [hidden]")
151
- Malformed auth headers (no auth type): Shows only "[hidden]"
152
- For 401, 403, and 404 status codes, adds helpful hint about authorization
153

154
This prevents sensitive authentication tokens from appearing in logs or error reports.