Error handling

Every factory and every model method in the zoo throws RunntimeError when something goes wrong. It is a regular Error with an extra code field. Check err.code to decide what to do. The message is text for people and can change between versions, so do not compare it.

Catching errors

isRunntimeError(err, code) tells you whether err is a ruNNtime error with that code. It also narrows the type, so err.code and err.cause are typed inside the branch.

import { 
function createImageClassifier(config?: ImageClassifierModel, opts?: LoadOptions): Promise<ImageClassifier>
createImageClassifier, 
function isRunntimeError<C extends RunntimeErrorCode>(value: unknown, code?: C): value is RunntimeError<C>
isRunntimeError, 
const models: {
    readonly embedding: {
        readonly EMBEDDINGGEMMA_2: {
            DEFAULT: {
                modelPath: string;
                visionPath: string;
                audioPath: string;
                tokenizerPath: string;
            };
            F16: {
                dtype: "f16";
                modelPath: string;
                visionPath: string;
                audioPath: string;
                tokenizerPath: string;
            };
            F32: {
                dtype: "f32";
                modelPath: string;
                visionPath: string;
                audioPath: string;
                tokenizerPath: string;
            };
        };
        readonly ALL_MINILM_L6_V2: {
            DEFAULT: {
                tokenizerPath: string;
            } & {
                modelPath: string;
            };
            F16: {
                tokenizerPath: string;
            } & {
                dtype: "f16";
                modelPath: string;
            };
            F32: {
                tokenizerPath: string;
            } & {
                modelPath: string;
                dtype: "f32";
            };
        };
    };
    ... 6 more ...;
    readonly imageClassification: {
        readonly MOBILENETV4: {
            readonly DEFAULT: {
                modelPath: string;
            };
            readonly SMALL: {
                modelPath: string;
            };
        };
    };
}
models } from 'runntime/zoo';

let 
let classifier: any
classifier;
try {
  
let classifier: any
classifier = await 
function createImageClassifier(config?: ImageClassifierModel, opts?: LoadOptions): Promise<ImageClassifier>
createImageClassifier(
const models: {
    readonly embedding: {
        readonly EMBEDDINGGEMMA_2: {
            DEFAULT: {
                modelPath: string;
                visionPath: string;
                audioPath: string;
                tokenizerPath: string;
            };
            F16: {
                dtype: "f16";
                modelPath: string;
                visionPath: string;
                audioPath: string;
                tokenizerPath: string;
            };
            F32: {
                dtype: "f32";
                modelPath: string;
                visionPath: string;
                audioPath: string;
                tokenizerPath: string;
            };
        };
        readonly ALL_MINILM_L6_V2: {
            DEFAULT: {
                tokenizerPath: string;
            } & {
                modelPath: string;
            };
            F16: {
                tokenizerPath: string;
            } & {
                dtype: "f16";
                modelPath: string;
            };
            F32: {
                tokenizerPath: string;
            } & {
                modelPath: string;
                dtype: "f32";
            };
        };
    };
    ... 6 more ...;
    readonly imageClassification: {
        readonly MOBILENETV4: {
            readonly DEFAULT: {
                modelPath: string;
            };
            readonly SMALL: {
                modelPath: string;
            };
        };
    };
}
models.
imageClassification: {
    readonly MOBILENETV4: {
        readonly DEFAULT: {
            modelPath: string;
        };
        readonly SMALL: {
            modelPath: string;
        };
    };
}
imageClassification.
type MOBILENETV4: {
    readonly DEFAULT: {
        modelPath: string;
    };
    readonly SMALL: {
        modelPath: string;
    };
}
MOBILENETV4.
type DEFAULT: {
    modelPath: string;
}
DEFAULT);
} catch (
var err: unknown
err) {
  if (
isRunntimeError<"UNSUPPORTED_DEVICE">(value: unknown, code?: "UNSUPPORTED_DEVICE" | undefined): value is RunntimeError<"UNSUPPORTED_DEVICE">
isRunntimeError(
var err: unknown
err, 'UNSUPPORTED_DEVICE')) 
function showNoF16Message(): void
showNoF16Message();
  if (
isRunntimeError<"LOAD_FAILED">(value: unknown, code?: "LOAD_FAILED" | undefined): value is RunntimeError<"LOAD_FAILED">
isRunntimeError(
var err: unknown
err, 'LOAD_FAILED')) 
function showOfflineMessage(): void
showOfflineMessage();
  throw 
var err: unknown
err;
}

The same works for a model method:

try {
  
function showResults(results: (Classification & {
    label: string;
})[]): void
showResults(await 
const classifier: ImageClassifier
classifier.
ImageClassifier.classify(image: ImageBuffer, options?: ClassifyOptions): Promise<(Classification & {
    label: string;
})[]>
classify(
const image: ImageBuffer
image, { 
ClassifyOptions.topk?: number | undefined
topk: 5 }));
} catch (
var err: unknown
err) {
  if (
isRunntimeError<"INVALID_ARGUMENT">(value: unknown, code?: "INVALID_ARGUMENT" | undefined): value is RunntimeError<"INVALID_ARGUMENT">
isRunntimeError(
var err: unknown
err, 'INVALID_ARGUMENT')) 
function showBadImageMessage(): void
showBadImageMessage();
  if (
isRunntimeError<"EXECUTION_FAILED">(value: unknown, code?: "EXECUTION_FAILED" | undefined): value is RunntimeError<"EXECUTION_FAILED">
isRunntimeError(
var err: unknown
err, 'EXECUTION_FAILED')) 
function showGpuErrorMessage(): void
showGpuErrorMessage();
  throw 
var err: unknown
err;
}

EXECUTION_FAILED can mean the device was lost. A lost device takes every model on it, and loading again on the same device fails too. To recover, create a new device with tgpu.init(), pass it to initRunntime(), then load the models again.

isRunntimeError(err) without a code tells a ruNNtime error from any other. err.cause holds the original error where there is one, like the failed fetch.

Codes

Code	When
`LOAD_FAILED`	The weights, tokenizer or config could not be fetched, read or uploaded.
`LOAD_ABORTED`	The `signal` passed to the `create` call fired.
`CHECKPOINT_MISMATCH`	The weights file does not match the model, for example a segment checkpoint given to object detection.
`UNSUPPORTED_DEVICE`	The device lacks a feature the model needs, today `shader-f16` for the vision models, or a weight is too big for the device to bind.
`NOT_INITIALIZED`	No device yet: `initRunntime(root)` was not called before the `create` call.
`EXECUTION_FAILED`	The GPU rejected the work, returned unusable output, or the device was lost during a call.
`INVALID_ARGUMENT`	A value you passed is wrong: a wrong image byte count, a `topk` of 0, text that is not a string.
`RESOURCE_DISPOSED`	The model was disposed and cannot run again.

LOAD_FAILED, LOAD_ABORTED, CHECKPOINT_MISMATCH, UNSUPPORTED_DEVICE and NOT_INITIALIZED come from the create call, the other three from the model methods. A create call can also throw INVALID_ARGUMENT when an option is wrong, and EXECUTION_FAILED when the GPU fails while the model uploads or warms up.

The full list of codes is exported as RUNNTIME_ERROR_CODES, and the type of one code as RunntimeErrorCode.

Cancelling a load

Every create call takes an AbortSignal. Use it when the user leaves the page or picks another model before the first one is ready. When it fires, the load stops, at the latest when its current step ends, and the call throws LOAD_ABORTED. This works for any reason you pass to abort(). The reason is in err.cause.

const 
const controller: AbortController
controller = new 
var AbortController: new () => AbortController
AbortController();
const cancelButton: HTMLButtonElement
cancelButton.
GlobalEventHandlers.onclick: ((this: GlobalEventHandlers, ev: PointerEvent) => any) | null
onclick = () => 
const controller: AbortController
controller.
AbortController.abort(reason?: any): void
abort();

try {
  
let classifier: ImageClassifier
classifier = await 
function createImageClassifier(config?: ImageClassifierModel, opts?: LoadOptions): Promise<ImageClassifier>
createImageClassifier(
const models: {
    readonly embedding: {
        readonly EMBEDDINGGEMMA_2: {
            DEFAULT: {
                modelPath: string;
                visionPath: string;
                audioPath: string;
                tokenizerPath: string;
            };
            F16: {
                dtype: "f16";
                modelPath: string;
                visionPath: string;
                audioPath: string;
                tokenizerPath: string;
            };
            F32: {
                dtype: "f32";
                modelPath: string;
                visionPath: string;
                audioPath: string;
                tokenizerPath: string;
            };
        };
        readonly ALL_MINILM_L6_V2: {
            DEFAULT: {
                tokenizerPath: string;
            } & {
                modelPath: string;
            };
            F16: {
                tokenizerPath: string;
            } & {
                dtype: "f16";
                modelPath: string;
            };
            F32: {
                tokenizerPath: string;
            } & {
                modelPath: string;
                dtype: "f32";
            };
        };
    };
    ... 6 more ...;
    readonly imageClassification: {
        readonly MOBILENETV4: {
            readonly DEFAULT: {
                modelPath: string;
            };
            readonly SMALL: {
                modelPath: string;
            };
        };
    };
}
models.
imageClassification: {
    readonly MOBILENETV4: {
        readonly DEFAULT: {
            modelPath: string;
        };
        readonly SMALL: {
            modelPath: string;
        };
    };
}
imageClassification.
type MOBILENETV4: {
    readonly DEFAULT: {
        modelPath: string;
    };
    readonly SMALL: {
        modelPath: string;
    };
}
MOBILENETV4.
type DEFAULT: {
    modelPath: string;
}
DEFAULT, {
    
LoadOptions.signal?: AbortSignal | undefined
signal: 
const controller: AbortController
controller.
AbortController.signal: AbortSignal
signal,
  });
} catch (
var err: unknown
err) {
  // The user cancelled: nothing to do.
  if (!
isRunntimeError<"LOAD_ABORTED">(value: unknown, code?: "LOAD_ABORTED" | undefined): value is RunntimeError<"LOAD_ABORTED">
isRunntimeError(
var err: unknown
err, 'LOAD_ABORTED')) throw 
var err: unknown
err;
}