Skip to content

Commit 98d843e

Browse files
chmjkbchmjkb
committed
docs: add docs for error handling
1 parent 9516a30 commit 98d843e

File tree

1 file changed

+179
-0
lines changed

1 file changed

+179
-0
lines changed

‎docs/docs/03-typescript-api/04-error-handling.md‎

Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
---
2+
title: Error handling
3+
---
4+
5+
## Overview
6+
7+
In order to handle different types of errors, you can use `instanceof` with our exported class `ExecutorchError` and its `code` property. This allows you to check what exactly went wrong and act accordingly.
8+
9+
This example uses the `LLMModule`, and then tries to change its `generationConfig`. As the topp param has to be a value between 0 and 1 (inclusive), the `.configure()` method will throw an error with a code InvalidConfig.
10+
11+
```typescript
12+
import {
13+
LLMModule,
14+
LLAMA3_2_1B_QLORA,
15+
ExecutorchError,
16+
ETErrorCode,
17+
} from 'react-native-executorch';
18+
19+
const llm = new LLMModule({
20+
tokenCallback: (token) => console.log(token),
21+
messageHistoryCallback: (messages) => console.log(messages),
22+
});
23+
24+
await llm.load(LLAMA3_2_1B_QLORA, (progress) => console.log(progress));
25+
26+
// Try to set an invalid configuration
27+
try {
28+
await llm.configure({ topp: 1.5 }); // This will throw InvalidConfig error
29+
} catch (err) {
30+
if (
31+
err instanceof ExecutorchError &&
32+
err.code === ETErrorCode.InvalidConfig
33+
) {
34+
console.error('Invalid configuration:', err.message);
35+
// Handle the invalid config - set default values
36+
await llm.configure({ topp: 0.9 });
37+
} else {
38+
throw err;
39+
}
40+
}
41+
42+
// Running the model
43+
try {
44+
await llm.sendMessage('Hello, World!');
45+
} catch (err) {
46+
if (err instanceof ExecutorchError) {
47+
if (err.code === ETErrorCode.ModuleNotLoaded) {
48+
console.error('Model not loaded:', err.message);
49+
// Load the model first
50+
} else if (err.code === ETErrorCode.ModelGenerating) {
51+
console.error('Model is already generating:', err.message);
52+
// Wait for current generation to complete
53+
} else {
54+
console.error('Generation error:', err.message);
55+
throw err;
56+
}
57+
} else {
58+
throw err;
59+
}
60+
}
61+
62+
// Interrupting the model (to actually interrupt the generation it has to be called when sendMessage or generate is running)
63+
llm.interrupt();
64+
65+
// Deleting the model from memory
66+
llm.delete();
67+
```
68+
69+
## Reference
70+
71+
All errors in React Native ExecuTorch inherit from `ExecutorchError` and include a `code` property from the `ETErrorCode` enum. Below is a comprehensive list of all possible errors, organized by category.
72+
73+
### Module State Errors
74+
75+
These errors occur when trying to perform operations on a model in an invalid state.
76+
77+
| Error Code | Description | When It Occurs | How to Handle |
78+
| ----------------- | ------------------------------------- | ------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
79+
| `ModuleNotLoaded` | Model is not loaded into memory | Calling `forward()`, `generate()`, or other inference methods before calling `load()` | Load the model first with `load()` |
80+
| `ModelGenerating` | Model is already processing a request | Calling `generate()` or `forward()` while another inference is running | Wait for current generation to complete, or use `interrupt()` to cancel it |
81+
82+
### Configuration Errors
83+
84+
These errors occur when invalid configuration or input is provided.
85+
86+
| Error Code | Description | When It Occurs | How to Handle |
87+
| ---------------------- | ------------------------------------ | ------------------------------------------------------------------------- | ---------------------------------------------------- |
88+
| `InvalidConfig` | Configuration parameters are invalid | Setting parameters outside valid ranges (e.g., `topp` outside [0, 1]) | Check parameter constraints and provide valid values |
89+
| `InvalidUserInput` | Input provided to API is invalid | Passing empty arrays, null values, or malformed data to methods | Validate input before calling methods |
90+
| `InvalidModelSource` | Model source type is invalid | Providing wrong type for model source (e.g., object when string expected) | Ensure model source matches expected type |
91+
| `LanguageNotSupported` | Language not supported by model | Passing unsupported language to multilingual OCR or Speech-to-Text models | Use a supported language or different model |
92+
| `WrongDimensions` | Input tensor dimensions don't match | Providing input with incorrect shape for the model | Check model's expected input dimensions |
93+
| `UnexpectedNumInputs` | Wrong number of inputs provided | Passing more or fewer inputs than model expects | Match the number of inputs to model metadata |
94+
95+
### File Operations Errors
96+
97+
These errors occur during file read/write operations.
98+
99+
| Error Code | Description | When It Occurs | How to Handle |
100+
| ----------------- | --------------------------- | ------------------------------------------------------------ | --------------------------------------------- |
101+
| `FileReadFailed` | File read operation failed | Invalid image URL, unsupported format, or file doesn't exist | Verify file path and format are correct |
102+
| `FileWriteFailed` | File write operation failed | Saving result image or output file fails | Check storage permissions and available space |
103+
104+
### Download & Resource Fetcher Errors
105+
106+
These errors occur during model download and resource management.
107+
108+
| Error Code | Description | When It Occurs | How to Handle |
109+
| ----------------------------------- | -------------------------------- | ----------------------------------------------------- | ------------------------------------------------------------------------- |
110+
| `DownloadInterrupted` | Download was interrupted | Not all files were downloaded successfully | Retry the download |
111+
| `ResourceFetcherDownloadFailed` | Resource download failed | Network error, invalid URL, or server error | Check network connection and URL validity, retry with exponential backoff |
112+
| `ResourceFetcherDownloadInProgress` | Download already in progress | Calling `fetch()` for same resource while downloading | Wait for current download to complete |
113+
| `ResourceFetcherAlreadyPaused` | Download already paused | Calling `pauseFetching()` on already paused download | Check download state before pausing |
114+
| `ResourceFetcherAlreadyOngoing` | Download already ongoing | Calling `resumeFetching()` on active download | No action needed, download is already running |
115+
| `ResourceFetcherNotActive` | No active download found | Calling pause/resume/cancel on non-existent download | Verify download was started before trying to control it |
116+
| `ResourceFetcherMissingUri` | Required URI information missing | Internal state error during download operations | Restart the download from beginning |
117+
118+
### Speech-to-Text Streaming Errors
119+
120+
These errors are specific to streaming transcription operations.
121+
122+
| Error Code | Description | When It Occurs | How to Handle |
123+
| --------------------------- | ----------------------------------- | ----------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
124+
| `MultilingualConfiguration` | Multilingual configuration mismatch | Setting language on non-multilingual model, or not setting language on multilingual model | Check if model is multilingual and provide language accordingly |
125+
| `MissingDataChunk` | Audio data chunk missing | Streaming transcription without providing audio data | Ensure audio data is provided to streaming methods |
126+
| `StreamingNotStarted` | Stream not started | Calling `stop()` or `insertData()` without calling `start()` first | Call `start()` before other streaming operations |
127+
| `StreamingInProgress` | Stream already in progress | Calling `start()` while another stream is active | Stop current stream before starting a new one |
128+
129+
### Model Execution Errors
130+
131+
These errors come from the ExecuTorch runtime during model execution.
132+
133+
| Error Code | Description | When It Occurs | How to Handle |
134+
| -------------------- | ---------------------------- | ---------------------------------------------- | ---------------------------------------------- |
135+
| `InvalidModelOutput` | Model output size unexpected | Model produces output of wrong size | Verify model is compatible with the library |
136+
| `ThreadPoolError` | Threadpool operation failed | Internal threading issue | Restart the model or app |
137+
| `UnknownError` | Unexpected error occurred | 3rd-party library error or unhandled exception | Check logs for details, report if reproducible |
138+
139+
### ExecuTorch Runtime Errors
140+
141+
These errors are mapped directly from the ExecuTorch runtime. They typically indicate lower-level execution issues.
142+
143+
#### System Errors
144+
145+
| Error Code | Description |
146+
| -------------- | ----------------------------------- |
147+
| `Ok` | Operation successful (not an error) |
148+
| `Internal` | Internal ExecuTorch error |
149+
| `InvalidState` | Operation called in invalid state |
150+
| `EndOfMethod` | End of method reached |
151+
152+
#### Logical Errors
153+
154+
| Error Code | Description |
155+
| ----------------- | ------------------------------------ |
156+
| `NotSupported` | Operation not supported by model |
157+
| `NotImplemented` | Feature not implemented |
158+
| `InvalidArgument` | Invalid argument passed to operation |
159+
| `InvalidType` | Type mismatch in operation |
160+
| `OperatorMissing` | Required operator missing from model |
161+
162+
#### Resource Errors
163+
164+
| Error Code | Description |
165+
| ------------------------ | -------------------------- |
166+
| `NotFound` | Resource not found |
167+
| `MemoryAllocationFailed` | Memory allocation failed |
168+
| `AccessFailed` | Access to resource failed |
169+
| `InvalidProgram` | Model program is invalid |
170+
| `InvalidExternalData` | External data is invalid |
171+
| `OutOfResources` | System resources exhausted |
172+
173+
#### Delegate Errors
174+
175+
| Error Code | Description |
176+
| -------------------------------- | ---------------------------------- |
177+
| `DelegateInvalidCompatibility` | Delegate not compatible with model |
178+
| `DelegateMemoryAllocationFailed` | Delegate memory allocation failed |
179+
| `DelegateInvalidHandle` | Invalid delegate handle |

0 commit comments

Comments
 (0)