0
# Error Handling
1

2
Vue Compiler Core provides a comprehensive error handling system with detailed error codes, source location tracking, and human-readable error messages for all compilation phases.
3

4
## Capabilities
5

6
### Error Codes
7

8
Enumeration of all possible compiler error conditions.
9

10
```typescript { .api }
11
/**
12
 * Enumeration of all compiler error codes
13
 */
14
enum ErrorCodes {
15
  // Parse errors
16
  ABRUPT_CLOSING_OF_EMPTY_COMMENT = 0,
17
  CDATA_IN_HTML_CONTENT = 1,
18
  DUPLICATE_ATTRIBUTE = 2,
19
  END_TAG_WITH_ATTRIBUTES = 3,
20
  END_TAG_WITH_TRAILING_SOLIDUS = 4,
21
  EOF_BEFORE_TAG_NAME = 5,
22
  EOF_IN_CDATA = 6,
23
  EOF_IN_COMMENT = 7,
24
  EOF_IN_SCRIPT_HTML_COMMENT_LIKE_TEXT = 8,
25
  EOF_IN_TAG = 9,
26
  INCORRECTLY_CLOSED_COMMENT = 10,
27
  INCORRECTLY_OPENED_COMMENT = 11,
28
  INVALID_FIRST_CHARACTER_OF_TAG_NAME = 12,
29
  MISSING_ATTRIBUTE_VALUE = 13,
30
  MISSING_END_TAG_NAME = 14,
31
  MISSING_WHITESPACE_BETWEEN_ATTRIBUTES = 15,
32
  NESTED_COMMENT = 16,
33
  UNEXPECTED_CHARACTER_IN_ATTRIBUTE_NAME = 17,
34
  UNEXPECTED_CHARACTER_IN_UNQUOTED_ATTRIBUTE_VALUE = 18,
35
  UNEXPECTED_EQUALS_SIGN_BEFORE_ATTRIBUTE_NAME = 19,
36
  UNEXPECTED_NULL_CHARACTER = 20,
37
  UNEXPECTED_QUESTION_MARK_INSTEAD_OF_TAG_NAME = 21,
38
  UNEXPECTED_SOLIDUS_IN_TAG = 22,
39

40
  // Vue-specific parse errors
41
  X_INVALID_END_TAG = 23,
42
  X_MISSING_END_TAG = 24,
43
  X_MISSING_INTERPOLATION_END = 25,
44
  X_MISSING_DIRECTIVE_NAME = 26,
45
  X_MISSING_DYNAMIC_DIRECTIVE_ARGUMENT_END = 27,
46

47
  // Transform errors
48
  X_V_IF_NO_EXPRESSION = 28,
49
  X_V_IF_SAME_KEY = 29,
50
  X_V_ELSE_NO_ADJACENT_IF = 30,
51
  X_V_FOR_NO_EXPRESSION = 31,
52
  X_V_FOR_MALFORMED_EXPRESSION = 32,
53
  X_V_FOR_TEMPLATE_KEY_PLACEMENT = 33,
54
  X_V_BIND_NO_EXPRESSION = 34,
55
  X_V_ON_NO_EXPRESSION = 35,
56
  X_V_SLOT_UNEXPECTED_DIRECTIVE_ON_SLOT_OUTLET = 36,
57
  X_V_SLOT_MIXED_SLOT_USAGE = 37,
58
  X_V_SLOT_DUPLICATE_SLOT_NAMES = 38,
59
  X_V_SLOT_EXTRANEOUS_DEFAULT_SLOT_CHILDREN = 39,
60
  X_V_SLOT_MISPLACED = 40,
61
  X_V_MODEL_NO_EXPRESSION = 41,
62
  X_V_MODEL_MALFORMED_EXPRESSION = 42,
63
  X_V_MODEL_ON_SCOPE_VARIABLE = 43,
64
  X_V_MODEL_ON_PROPS = 44,
65
  X_INVALID_EXPRESSION = 45,
66
  X_KEEP_ALIVE_INVALID_CHILDREN = 46,
67

68
  // Generic errors
69
  X_PREFIX_ID_NOT_SUPPORTED = 47,
70
  X_MODULE_MODE_NOT_SUPPORTED = 48,
71
  X_CACHE_HANDLER_NOT_SUPPORTED = 49,
72
  X_SCOPE_ID_NOT_SUPPORTED = 50
73
}
74
```
75

76
### Error Messages
77

78
Mapping of error codes to human-readable messages.
79

80
```typescript { .api }
81
/**
82
 * Map of error codes to default error messages
83
 */
84
const errorMessages: Record<ErrorCodes, string>;
85
```
86

87
**Error Message Examples:**
88

89
```typescript
90
// Example error messages
91
errorMessages[ErrorCodes.DUPLICATE_ATTRIBUTE] = "Duplicate attribute.";
92
errorMessages[ErrorCodes.X_V_IF_NO_EXPRESSION] = "v-if is missing expression.";
93
errorMessages[ErrorCodes.X_V_FOR_MALFORMED_EXPRESSION] = "v-for has invalid expression.";
94
```
95

96
### Error Creation
97

98
Functions for creating compiler errors with location information.
99

100
```typescript { .api }
101
/**
102
 * Creates a compiler error with location information
103
 * @param code - Error code from ErrorCodes enum
104
 * @param loc - Source location where error occurred
105
 * @param messages - Custom error messages (optional)
106
 * @param additionalMessage - Additional error context (optional)
107
 * @returns Compiler error instance
108
 */
109
function createCompilerError<T extends number>(
110
  code: T,
111
  loc?: SourceLocation,
112
  messages?: { [code: number]: string },
113
  additionalMessage?: string
114
): InferCompilerError<T>;
115
```
116

117
**Usage Examples:**
118

119
```typescript
120
import { createCompilerError, ErrorCodes } from "@vue/compiler-core";
121

122
// Create error with location
123
const error = createCompilerError(
124
  ErrorCodes.X_V_IF_NO_EXPRESSION,
125
  sourceLocation,
126
  undefined,
127
  "Expected expression after v-if directive"
128
);
129

130
// Create error with custom messages
131
const customMessages = {
132
  [ErrorCodes.DUPLICATE_ATTRIBUTE]: "Found duplicate attribute, this is not allowed"
133
};
134

135
const error = createCompilerError(
136
  ErrorCodes.DUPLICATE_ATTRIBUTE,
137
  sourceLocation,
138
  customMessages
139
);
140
```
141

142
## Error Interfaces
143

144
Type definitions for compiler errors.
145

146
### Core Compiler Error
147

148
Base interface for all compiler errors.
149

150
```typescript { .api }
151
/**
152
 * Core compiler error interface
153
 */
154
interface CoreCompilerError extends Error {
155
  /** Error code from ErrorCodes enum */
156
  code: number;
157
  /** Source location where error occurred */
158
  loc?: SourceLocation;
159
}
160
```
161

162
### Compiler Error
163

164
Extended compiler error interface with additional properties.
165

166
```typescript { .api }
167
/**
168
 * Compiler error interface extending SyntaxError
169
 */
170
interface CompilerError extends SyntaxError {
171
  /** Error code from ErrorCodes enum */  
172
  code: number;
173
  /** Source location where error occurred */
174
  loc?: SourceLocation;
175
}
176
```
177

178
### Error Type Inference
179

180
Utility type for inferring specific error types.
181

182
```typescript { .api }
183
/**
184
 * Infers the specific compiler error type based on error code
185
 */
186
type InferCompilerError<T extends number> = T extends ErrorCodes
187
  ? CoreCompilerError
188
  : CompilerError;
189
```
190

191
## Error Handling Patterns
192

193
### Parse Error Handling
194

195
Errors that occur during template parsing phase.
196

197
```typescript { .api }
198
// Example of how parse errors are handled internally
199
function handleParseError(
200
  context: ParserContext,
201
  code: ErrorCodes,
202
  offset?: number
203
) {
204
  const loc = getCursor(context, offset);
205
  const error = createCompilerError(code, loc);
206
  context.onError(error);
207
}
208
```
209

210
**Common Parse Errors:**
211

212
- `DUPLICATE_ATTRIBUTE` - Multiple attributes with same name
213
- `MISSING_ATTRIBUTE_VALUE` - Attribute without value where required
214
- `EOF_IN_TAG` - Unexpected end of file inside tag
215
- `X_MISSING_END_TAG` - Missing closing tag for element
216
- `X_MISSING_INTERPOLATION_END` - Unclosed interpolation {{ }}
217

218
### Transform Error Handling
219

220
Errors that occur during AST transformation phase.
221

222
```typescript { .api }
223
// Example of transform error handling
224
function validateDirective(
225
  dir: DirectiveNode, 
226
  context: TransformContext
227
) {
228
  if (dir.name === 'if' && !dir.exp) {
229
    context.onError(
230
      createCompilerError(
231
        ErrorCodes.X_V_IF_NO_EXPRESSION,
232
        dir.loc
233
      )
234
    );
235
  }
236
}
237
```
238

239
**Common Transform Errors:**
240

241
- `X_V_IF_NO_EXPRESSION` - v-if without condition
242
- `X_V_FOR_MALFORMED_EXPRESSION` - Invalid v-for syntax
243
- `X_V_MODEL_ON_SCOPE_VARIABLE` - v-model on v-for variable
244
- `X_INVALID_EXPRESSION` - Invalid JavaScript expression
245
- `X_V_SLOT_MISPLACED` - v-slot used incorrectly
246

247
### Error Reporting Functions
248

249
Default error handling functions provided by the compiler.
250

251
```typescript { .api }
252
/**
253
 * Default error handler that throws the error
254
 * @param error - Compiler error to handle
255
 */
256
function defaultOnError(error: CompilerError): never;
257

258
/**
259
 * Default warning handler that logs the warning
260
 * @param warning - Compiler warning to handle
261
 */
262
function defaultOnWarn(warning: CompilerError): void;
263
```
264

265
**Usage Examples:**
266

267
```typescript
268
import { baseCompile, defaultOnError } from "@vue/compiler-core";
269

270
// Use custom error handler
271
const result = baseCompile(template, {
272
  onError: (error) => {
273
    console.error(`Compilation error: ${error.message}`);
274
    if (error.loc) {
275
      console.error(`At line ${error.loc.start.line}, column ${error.loc.start.column}`);
276
    }
277
  }
278
});
279

280
// Use default error handler (throws)
281
const result = baseCompile(template, {
282
  onError: defaultOnError
283
});
284
```
285

286
## Error Context Integration
287

288
### Parser Context Errors
289

290
How errors integrate with parser context.
291

292
```typescript { .api }
293
interface ParserOptions {
294
  /** Error handler function */
295
  onError?: (error: CompilerError) => void;
296
  /** Warning handler function */
297
  onWarn?: (warning: CompilerError) => void;
298
}
299
```
300

301
### Transform Context Errors
302

303
How errors integrate with transform context.
304

305
```typescript { .api }
306
interface TransformOptions {
307
  /** Error handler function */
308
  onError?: (error: CompilerError) => void;
309
  /** Warning handler function */
310
  onWarn?: (warning: CompilerError) => void;
311
}
312
```
313

314
## Code Frame Generation
315

316
Function for generating helpful code frames for error display.
317

318
```typescript { .api }
319
/**
320
 * Generates a code frame showing the error location in context
321
 * @param source - Original source code
322
 * @param start - Start position of error
323
 * @param end - End position of error  
324
 * @returns Formatted code frame string
325
 */
326
function generateCodeFrame(
327
  source: string,
328
  start?: number,
329
  end?: number
330
): string;
331
```
332

333
**Usage Examples:**
334

335
```typescript
336
import { generateCodeFrame } from "@vue/compiler-core";
337

338
const source = `<template>
339
  <div v-if>No condition</div>
340
</template>`;
341

342
const error = createCompilerError(
343
  ErrorCodes.X_V_IF_NO_EXPRESSION,
344
  { start: { offset: 15 }, end: { offset: 20 } }
345
);
346

347
// Generate helpful code frame
348
const codeFrame = generateCodeFrame(
349
  source, 
350
  error.loc.start.offset, 
351
  error.loc.end.offset
352
);
353

354
console.log(codeFrame);
355
// Output:
356
// 2 |    <div v-if>No condition</div>
357
//   |         ^^^^^
358
```
359

360
## Error Recovery
361

362
The compiler includes error recovery mechanisms to continue compilation after encountering errors.
363

364
### Recovery Strategies
365

366
- **Skip malformed tokens** - Continue parsing after invalid syntax
367
- **Synthesize missing elements** - Create placeholder nodes for missing content
368
- **Fallback transforms** - Use safe defaults when transforms fail
369
- **Graceful degradation** - Reduce optimization level rather than failing
370

371
### Error Collection
372

373
```typescript { .api }
374
interface CompilerOptions {
375
  /** Collect all errors instead of throwing on first error */
376
  collectErrors?: boolean;
377
}
378

379
// When collectErrors is true, errors are collected and returned
380
interface CodegenResult {
381
  code: string;
382
  preamble: string;  
383
  ast: RootNode;
384
  map?: RawSourceMap;
385
  /** Collected errors during compilation */
386
  errors?: CompilerError[];
387
}
388
```
389

390
**Usage Examples:**
391

392
```typescript
393
import { baseCompile } from "@vue/compiler-core";
394

395
// Collect all errors
396
const result = baseCompile(template, {
397
  collectErrors: true,
398
  onError: (error) => {
399
    // Errors are collected but don't stop compilation
400
    console.warn(`Warning: ${error.message}`);
401
  }
402
});
403

404
if (result.errors && result.errors.length > 0) {
405
  console.log(`Found ${result.errors.length} compilation errors`);
406
  result.errors.forEach(error => {
407
    console.error(error.message);
408
  });
409
}
410
```