HQL Error Reporting System
This document describes how HQL detects, reports, and maps errors back to your original source code.
Table of Contents
- Overview
- Error Categories
- The Compilation Pipeline
- Position Tracking
- Source Map Chain
- Type Error Integration
- Error Message Format
- Error Codes Reference
- Troubleshooting
Overview
HQL reports errors from parsing, import resolution, transformation, type checking, code generation, and runtime execution. When something goes wrong, HQL reports the available:
- What went wrong (clear error message)
- Where it happened (file, line, column)
- Why it might have happened (suggestions)
- How to fix it (when possible)
┌──────────────────────────────────────────────────────────────────────────────┐
│ Example Error Output │
├──────────────────────────────────────────────────────────────────────────────┤
│ │
│ error[HQL1003] : Unexpected ')' - Check for a missing opening '(' ... │
│ --> src/math.hql:5:24 │
│ │ │
│ 5 │ (fn add [a, b] (+ a b))) │
│ │ ^ unmatched `)` │
│ │ │
│ help: Check for missing opening parenthesis '(' earlier in the code. │
│ │
└──────────────────────────────────────────────────────────────────────────────┘
Error Categories
HQL has four main categories of errors, each occurring at different stages:
┌─────────────────────────────────────────────────────────────────────────────┐
│ ERROR CATEGORIES │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ PARSE │ │ TRANSFORM │ │ TYPE │ │ RUNTIME │ │
│ │ ERRORS │──▶│ ERRORS │──▶│ ERRORS │──▶│ ERRORS │ │
│ │ │ │ │ │ │ │ │ │
│ │ HQL1xxx │ │ HQL4xxx │ │ TSxxxx │ │ HQL5xxx │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │ │ │ │ │
│ ▼ ▼ ▼ ▼ │
│ Syntax issues IR generation TypeScript Execution │
│ Invalid tokens Macro expansion type checker exceptions │
│ Mismatched ( ) Unknown forms Type mismatch Undefined vars │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
1. Parse Errors (HQL1xxx)
Occur when HQL cannot understand your code's structure.
// Missing closing parenthesis
(fn add [a, b] (+ a b) // ← HQL1001: Unclosed list
// Unterminated string literal
(print "oops) // ← HQL1002: Unclosed string
// Stray closing parenthesis
(+ 1 2)) // ← HQL1003: Unexpected ')'
2. Import Errors (HQL2xxx)
Occur when an imported module cannot be resolved.
// File does not exist
(import [helper] from "./missing.hql")
(helper) // ← error[HQL2002]: Module not found
3. Type Errors (HQL6004 / HQL610x)
Occur when the type checker finds type mismatches. HQL uses TypeScript's checker
as the backend but rewrites diagnostics into HQL-native error codes such as
HQL6101 and HQL6104 under error[HQL6004]: Type checking failed. The raw
TSxxxx code is not shown to you. Current hql run and hql compile both fail
closed when type checking fails; JavaScript is not emitted or executed.
// Type mismatch
(fn add [a:number, b:number] -> number (+ a b))
(add "hello" "world") // ← error[HQL6101]: Expected number but got string
4. Runtime Errors (HQL5xxx)
Occur when code executes but encounters a problem.
// Undefined variable (hyphens normalize to underscores in the message)
(print unknown-var) // ← HQL5001: unknown_var is not defined
The Compilation Pipeline
Understanding the pipeline helps you understand where errors come from:
┌──────────────────────────────────────────────────────────────────────────────┐
│ HQL COMPILATION PIPELINE │
└──────────────────────────────────────────────────────────────────────────────┘
YOUR CODE OUTPUT
│ ▲
▼ │
┌─────────────────┐ │
│ │ │
│ math.hql │ Your HQL source file │
│ │ │
└────────┬────────┘ │
│ │
│ PHASE 1: PARSING │
│ ───────────────── │
│ • Tokenize source code │
│ • Build Abstract Syntax Tree (AST) │
│ • Track line:column for each token │
│ • ERRORS: HQL1xxx (syntax errors) │
▼ │
┌─────────────────┐ │
│ │ │
│ AST │ Tree structure of your code │
│ (with pos) │ Each node has position info │
│ │ │
└────────┬────────┘ │
│ │
│ PHASE 2: TRANSFORMATION │
│ ─────────────────────── │
│ • Expand macros │
│ • Convert to IR (Intermediate Representation) │
│ • Preserve positions through transforms │
│ • ERRORS: HQL4xxx (transform errors) │
▼ │
┌─────────────────┐ │
│ │ │
│ IR │ Intermediate Representation │
│ (with pos) │ Normalized code structure │
│ │ │
└────────┬────────┘ │
│ │
│ PHASE 3: TYPESCRIPT GENERATION │
│ ────────────────────────────── │
│ • Generate TypeScript code │
│ • Include type annotations │
│ • Create SOURCE MAP 1 (HQL → TS) │
▼ │
┌─────────────────┐ │
│ │ │
│ generated.ts │ TypeScript code │
│ + source map │ Maps back to HQL positions │
│ │ │
└────────┬────────┘ │
│ │
│ PHASE 4: TYPE CHECKING │
│ ────────────────────── │
│ • TypeScript compiler analyzes types │
│ • Reports type mismatches │
│ • We map positions back to HQL │
│ • ERRORS: TSxxxx (type errors) │
▼ │
┌─────────────────┐ │
│ │ │
│ Type Errors │ Mapped to HQL positions │
│ (fatal) │ Displayed to user │
│ │ │
└────────┬────────┘ │
│ │
│ PHASE 5: JAVASCRIPT COMPILATION │
│ ─────────────────────────────── │
│ • TypeScript compiles to JavaScript │
│ • Creates SOURCE MAP 2 (TS → JS) │
│ • We chain: HQL → TS → JS = HQL → JS │
▼ │
┌─────────────────┐ │
│ │ │
│ output.js │ Final JavaScript │
│ + source map │ Chained map points to HQL │
│ │ │
└────────┬────────┘ │
│ │
│ PHASE 6: EXECUTION │
│ ────────────────── │
│ • JavaScript runs │
│ • Runtime errors occur here │
│ • Stack traces mapped to HQL │
│ • ERRORS: HQL5xxx (runtime errors) │
▼ │
┌─────────────────┐ │
│ │ │
│ Result or │◀─────────────────────────────────────────────────┘
│ Runtime Error │
│ │
└─────────────────┘
Position Tracking
HQL tracks the original position (line and column) of every piece of code through all transformations.
How Positions Flow Through the Pipeline
┌──────────────────────────────────────────────────────────────────────────────┐
│ POSITION TRACKING FLOW │
└──────────────────────────────────────────────────────────────────────────────┘
Original HQL:
─────────────
Line 3: (print (add "wrong" 5))
▲
└── Position: line=3, column=18
After Parsing (AST):
────────────────────
CallExpression {
callee: "add",
arguments: [
StringLiteral {
value: "wrong",
position: { line: 3, column: 18 } ← Position preserved!
},
NumberLiteral { value: 5, position: { line: 3, column: 26 } }
],
position: { line: 3, column: 9 }
}
After Transform (IR):
─────────────────────
IRCallExpression {
callee: IRIdentifier { name: "add" },
arguments: [
IRStringLiteral {
value: "wrong",
position: { line: 3, column: 18 } ← Still preserved!
},
...
]
}
Generated TypeScript:
─────────────────────
console.log(add("wrong", 5))//
▲
└── Generated at: line=7, column=17
Maps to HQL: line=3, column=18
Source Map Entry:
─────────────────
{
generated: { line: 7, column: 17 },
original: { line: 3, column: 18 },
source: "math.hql"
}
The emit() Function
Position tracking happens in the TypeScript generator:
// In ir-to-typescript.ts
private emit(text: string, irPosition?: IR.SourcePosition): void {
// Record mapping if we have original position
if (irPosition && irPosition.line !== undefined) {
this.mappings.push({
generated: {
line: this.currentLine,
column: this.currentColumn
},
original: {
line: irPosition.line,
column: irPosition.column
},
source: irPosition.filePath
})//
}
// Update current position in generated code
this.code += text//
// ... update currentLine/currentColumn
}
Source Map Chain
HQL creates a chain of source maps to trace from final JavaScript back to original HQL:
┌──────────────────────────────────────────────────────────────────────────────┐
│ SOURCE MAP CHAIN │
└──────────────────────────────────────────────────────────────────────────────┘
math.hql generated.ts output.js
──────── ──────────── ─────────
Line 3 Line 7 Line 5
Column 18 Column 17 Column 12
│ │ │
│ │ │
│ SOURCE MAP 1 │ SOURCE MAP 2 │
│ (HQL → TS) │ (TS → JS) │
│ │ │
▼ ▼ ▼
┌─────────┐ ┌─────────┐ ┌─────────┐
│ HQL │─────────────▶│ TS │──────────────▶│ JS │
│ Source │ │ Source │ │ Output │
└─────────┘ └─────────┘ └─────────┘
▲ │
│ │
│ CHAINED SOURCE MAP │
│ (HQL → JS) │
└──────────────────────────────────────────────────┘
│
▼
When error at JS 5:12
We look up: JS → TS → HQL
Result: HQL 3:18
Chaining Process
// In source-map-chain.ts
export async function chainSourceMaps(
hqlToTsMappings: SourceMapping[], // Map 1: HQL → TS
tsToJsMapJson: string, // Map 2: TS → JS (from tsc)
hqlSourcePath: string,
): Promise<ChainedSourceMap> {
// Build lookup: TS position → HQL position
const tsToHqlMap = new Map<string, Position>(); //
for (let mapping of hqlToTsMappings) {
const key = `${mapping.generated.line}:${mapping.generated.column}`; //
tsToHqlMap.set(key, mapping.original); //
}
// For each JS → TS mapping, look up TS → HQL
// Result: JS → HQL (chained)
}
Type Error Integration
HQL leverages TypeScript's type checker as a "free" type system:
┌──────────────────────────────────────────────────────────────────────────────┐
│ TYPE ERROR FLOW │
└──────────────────────────────────────────────────────────────────────────────┘
1. YOUR HQL CODE
─────────────────
(fn add [a:number, b:number] -> number (+ a b))
(print (add "wrong" 5))
▲
└── You made a type error here!
2. GENERATED TYPESCRIPT
───────────────────────
function add(a: number, b: number): number {
return a + b//
}
console.log(add("wrong", 5))//
▲
└── TypeScript sees this
3. TYPESCRIPT TYPE CHECKER
──────────────────────────
┌────────────────────────────────────────────────────────────────────────┐
│ TypeScript Compiler (tsc) │
│ │
│ "I found an error!" │
│ │
│ { │
│ message: "Argument of type 'string' is not assignable │
│ to parameter of type 'number'", │
│ code: 2345, │
│ file: "generated.ts", │
│ line: 4, │
│ column: 17 │
│ } │
│ │
└────────────────────────────────────────────────────────────────────────┘
4. TRANSLATE + MAP BACK TO HQL
──────────────────────────────
Source map lookup: TS 4:17 → HQL 2:13
TS2345 message rewritten into an HQL-native `HQL6101` diagnostic
(the raw `TSxxxx` code is not shown to the user).
5. DISPLAY TO USER
──────────────────
┌────────────────────────────────────────────────────────────────────────┐
│ │
│ error[HQL6101] at math.hql:2:13: Expected number but got string │
│ │
│ 2 │ (print (add "wrong" 5)) │
│ │ ▲▲▲▲▲▲▲ │
│ │
└────────────────────────────────────────────────────────────────────────┘
Type Errors Fail Closed
On current hql run, type errors fail before JavaScript execution:
$ deno run -A src/hql/cli.ts run math.hql
error[HQL6004]: Type checking failed:
math.hql:2:13 - error[HQL6101]: Expected number but got string
On hql compile, the same type errors fail the build and no JavaScript is
emitted:
$ deno run -A src/hql/cli.ts compile math.hql -o out.js
error[HQL6004]: Type checking failed:
math.hql:2:13 - error[HQL6101]: Expected number but got string
Error Message Format
All HQL errors follow a consistent format:
┌──────────────────────────────────────────────────────────────────────────────┐
│ ERROR MESSAGE ANATOMY │
└──────────────────────────────────────────────────────────────────────────────┘
error[HQL5001] : variable_name is not defined ← error code + message
--> src/app.hql:5:9 ← file:line:column
│
5 │ (print variable-name) ← source context
│ ^ not found in this scope ← caret + label
│
help: Check that `variable_name` is spelled ... ← suggestion (help:)
Some errors also append a note: line with extra context (for example, parse
errors note that every ( must have a matching )). HQL diagnostics stay
HQL-native and do not link out to upstream TypeScript documentation.
Components
| Component | Description |
|---|---|
| Error code | error[HQL5001] — unique identifier plus message |
Location (-->) | Full path with line:column |
| Source context | The line(s) of code, with a caret under the span |
help: | How to fix it (a "Did you mean …?" suggestion when a |
| close match is found) | |
note: | Extra context shown for some errors |
Error Domains
The code prefix indicates the owning HQL boundary:
HQLerrors come from language parsing, compilation, and runtime semantics.
Error Codes Reference
The numeric values below are the single source of truth in
src/common/error-codes.ts(enum HQLErrorCode). Keep this table in sync.
Parse Errors (HQL1xxx)
| Code | Description |
|---|---|
| HQL1001 | Unclosed list |
| HQL1002 | Unclosed string |
| HQL1003 | Unexpected token |
| HQL1004 | Unexpected EOF |
| HQL1005 | Invalid syntax |
| HQL1006 | Unclosed comment |
| HQL1007 | Invalid character |
Import Errors (HQL2xxx)
| Code | Description |
|---|---|
| HQL2001 | Invalid import syntax |
| HQL2002 | Module not found |
| HQL2003 | Circular import |
| HQL2004 | Invalid import path |
| HQL2005 | Import resolution failed |
| HQL2006 | Export not found |
Validation Errors (HQL3xxx)
| Code | Description |
|---|---|
| HQL3001 | Invalid function syntax |
| HQL3002 | Invalid class syntax |
| HQL3003 | Missing required argument |
| HQL3004 | Too many arguments |
| HQL3005 | Invalid parameter |
| HQL3006 | Invalid variable name |
| HQL3007 | Duplicate parameter |
| HQL3008 | Invalid expression |
| HQL3009 | Pure effect violation |
Transform Errors (HQL4xxx)
| Code | Description |
|---|---|
| HQL4001 | Transformation failed |
| HQL4002 | Unsupported feature |
| HQL4003 | Invalid AST node |
| HQL4004 | Transform type mismatch |
Runtime Errors (HQL5xxx)
| Code | Description |
|---|---|
| HQL5001 | Undefined variable |
| HQL5002 | Type mismatch |
| HQL5003 | Division by zero |
| HQL5004 | Null or undefined reference |
| HQL5005 | Function not found |
Codegen Errors (HQL6xxx)
| Code | Description |
|---|---|
| HQL6001 | Code generation failed |
| HQL6002 | Invalid codegen target |
| HQL6003 | Source map generation failed |
Macro Errors (HQL7xxx)
| Code | Description |
|---|---|
| HQL7001 | Invalid macro definition |
| HQL7002 | Macro expansion failed |
| HQL7003 | Invalid macro syntax |
| HQL7004 | Macro not found |
| HQL7005 | Macro recursion limit |
Type Errors (HQL6004 / HQL610x)
Type errors are detected by the TypeScript checker backend, then rewritten into
HQL-native messages under error[HQL6004]: Type checking failed; individual
diagnostics use HQL610x codes. The raw TSxxxx code is not surfaced to you.
The most common backend codes and the HQL-native message they translate to:
| Backend code | HQL-native message |
|---|---|
| TS2345 | Expected <type> but got <type> |
| TS2322 | Cannot use <type> where <type> is expected |
| TS2304 | Undefined binding: <name> |
| TS2339 | Property '<x>' does not exist on type '<y>' |
| TS2554 | Function expected N argument(s), got M |
Troubleshooting
Error Position Seems Wrong
If an error points to the wrong location:
- Check for macros - Macro-generated code might have positions from macro definition
- Check for multi-byte characters - Unicode might affect column counting
- Check imports - Error might be in an imported file
Type Error Not Detected
If a type error isn't being caught:
- Add type annotations - HQL uses gradual typing; untyped code isn't checked
- Annotate rest parameters - Prefer
...rest:Array<T>so the variadic tail is typed - Verify syntax - Type annotations attach to the binding with
name:Type
// Annotate the parameters you want checked
(fn add [a:number, b:number] -> number (+ a b))
// Commas between parameters are optional
(fn add [a:number b:number] -> number (+ a b))
Stack Trace Points to Generated Code
If runtime errors show JavaScript line numbers:
- Source maps should handle this - Check that .js.map file exists
- Use the HQL CLI - Directly running generated JavaScript might not load source maps
- Report a bug - If positions are wrong, please report it
See Also
- Type System Documentation - Full type annotation guide
- HQL Manual - Complete language reference
- Testing Guide - How to test HQL code
Production Readiness
This section documents the verified behavior and known limitations of HQL's error reporting system.
Current Verified Status
These checks are intentionally scoped to behavior proven by the current test suite. Do not describe the system as "100% accurate" unless every compiler, runtime, bundled-output, and host-integration path has fresh black-box proof.
| Surface | Verified behavior |
|---|---|
hql run runtime errors | Maps real-file runtime failures back to .hql source with highlighted context. |
| Imported HQL runtime errors | Maps failures in imported .hql modules to the imported source file. |
| Legacy HQL CLI parse errors | Prints error[HQL1001], source file, line/column, caret context, help, and note. |
| Run-path type diagnostics | Fails closed before execution, displays HQL-native type diagnostics, and uses 1-based HQL columns. |
| Compile-path type diagnostics | Fails closed, does not emit the target JS, displays 1-based HQL columns, and avoids duplicate run-warning output. |
| Compiled JS source maps | Final bundled inline maps include original .hql sources, and direct deno run compiled.js stack traces point back to .hql rather than .hql-cache/*.ts. |
| Runtime fallback precision | Runtime location resolution no longer invents exact HQL source locations through keyword-search fallback when no source map or metadata can prove the position. |
Known Limitations
The system now has meaningful black-box coverage for the main CLI and compiled JavaScript paths, but it is still not a Rust/Swift-grade diagnostic system. Remaining maturity work includes multi-span type diagnostics, richer type-error source context, and broader host-level verification outside the focused HQL CLI and Deno execution paths.
Historical Limitations
1. User-Defined Macro Positions (Same File)
Status: ✅ Fixed (December 2024)
When a user-defined macro and its call site are in the same file, type
errors in macro-expanded code may point to the macro definition instead of the
call site.
This bug has been fixed. The updateMetaRecursively function in
src/hql/s-exp/macro.ts now correctly updates positions when:
- No existing metadata
- Different source file (macro definition in another file)
- Same file but expression comes from earlier in file (macro definition)
// Example - now correctly reports line 5
(macro my-add [a, b]
`(+ ~a ~b)) // Line 2 - macro definition
(fn check [x:number] -> number x)
(check (my-add "x" 5)) // Line 5 - call site
// Diagnostic correctly reports line 5 (the call site), e.g.
// "error[HQL6101] at test.hql:5:16: Expected number but got string"
2. Property Access On Known Types
Status: By design (gradual typing)
Accessing a missing property never throws — at runtime it returns undefined.
Whether the checker flags the access depends on whether it can infer a type:
// The literal 42 is inferred as `number`, so the missing `.length` is flagged
// before execution.
(let x 42)
(print x.length) // → error[HQL6104]: Property 'length' does not
// exist on type 'number'
// A typed parameter is checked the same way.
(fn f [x:number] -> number
(.length x)) // → error[HQL6104]: Property 'length' does not
// exist on type 'number'
Workaround: Annotate values/parameters so the checker can verify property access; truly dynamic values are not checked.
Technical Implementation
For developers working on HQL itself:
| Component | File |
|---|---|
| Parser | src/hql/transpiler/pipeline/parser.ts |
| IR Generator | src/hql/transpiler/pipeline/syntax-transformer.ts |
| TS Generator | src/hql/transpiler/pipeline/ir-to-typescript.ts |
| Type Checker | src/hql/transpiler/pipeline/ts-compiler.ts |
| Source Maps | src/hql/transpiler/pipeline/source-map-chain.ts |
| Error Formatter | src/common/error.ts |
| Error Codes | src/common/error-codes.ts |