Throwing Exceptions

QuickJS provides functions to create and throw exceptions from C code. When a C function throws an exception, it returns JS_EXCEPTION, and the exception object is stored in the JSContext.

JS_Throw

Throws an exception in the current context.

Signature

JSValue JS_Throw(JSContext *ctx, JSValue obj);

Parameters

ctx - The JavaScript context
obj - The exception object to throw (takes ownership)

Return Value

Always returns JS_EXCEPTION. This value should be returned from your C function to indicate an exception occurred.

Description

JS_Throw() takes ownership of the exception object passed to it. The function stores the exception in the context and returns JS_EXCEPTION, which is a sentinel value indicating that an exception has occurred.

Example

static JSValue my_function(JSContext *ctx, JSValueConst this_val,
                          int argc, JSValueConst *argv) {
    if (argc < 1) {
        JSValue err = JS_NewError(ctx);
        JS_DefinePropertyValueStr(ctx, err, "message",
            JS_NewString(ctx, "Expected at least one argument"),
            JS_PROP_WRITABLE | JS_PROP_CONFIGURABLE);
        return JS_Throw(ctx, err);
    }
    
    // Normal function logic
    return JS_UNDEFINED;
}

Creating Custom Exceptions

You can create custom exception objects before throwing them:

// Create a plain error object
JSValue error = JS_NewError(ctx);

// Add custom properties
JS_DefinePropertyValueStr(ctx, error, "message",
    JS_NewString(ctx, "Custom error message"),
    JS_PROP_WRITABLE | JS_PROP_CONFIGURABLE);

JS_DefinePropertyValueStr(ctx, error, "code",
    JS_NewInt32(ctx, 42),
    JS_PROP_WRITABLE | JS_PROP_CONFIGURABLE);

// Throw the error
return JS_Throw(ctx, error);

Throwing Existing Values

You can throw any JavaScript value, not just error objects:

// Throw a string
return JS_Throw(ctx, JS_NewString(ctx, "Something went wrong"));

// Throw a number
return JS_Throw(ctx, JS_NewInt32(ctx, -1));

// Throw an object
JSValue obj = JS_NewObject(ctx);
JS_SetPropertyStr(ctx, obj, "reason", JS_NewString(ctx, "Invalid input"));
return JS_Throw(ctx, obj);

Best Practices

Always return JS_EXCEPTION: After calling JS_Throw(), immediately return its result.
Memory management: JS_Throw() takes ownership of the exception object, so don’t call JS_FreeValue() on it.
Use appropriate error types: Use the specific error constructors (see Error Types) for standard JavaScript errors.
Add context: Include meaningful error messages and additional properties to help with debugging.

Runtime Management

Context Management

Value Operations

Function Calls

Object Operations

Script Evaluation

Exception Handling

Atoms

Throwing Exceptions

Throwing Exceptions

JS_Throw

Signature

Parameters

Return Value

Description

Example

Creating Custom Exceptions

Throwing Existing Values

Best Practices

See Also

​Throwing Exceptions

​JS_Throw

​Signature

​Parameters

​Return Value

​Description

​Example

​Creating Custom Exceptions

​Throwing Existing Values

​Best Practices

​See Also

Throwing Exceptions

JS_Throw

Signature

Parameters

Return Value

Description

Example

Creating Custom Exceptions

Throwing Existing Values

Best Practices

See Also