0
# Application and Manager Errors
1

2
Error classes for Ledger application management including app installation, dependencies, firmware updates, and manager operations.
3

4
## Capabilities
5

6
### Application Installation Errors
7

8
Errors related to installing and managing applications on Ledger devices.
9

10
```typescript { .api }
11
const ManagerAppAlreadyInstalledError: CustomErrorFunc;
12
const ManagerAppRelyOnBTCError: CustomErrorFunc;
13
const ManagerAppDepInstallRequired: CustomErrorFunc;
14
const ManagerAppDepUninstallRequired: CustomErrorFunc;
15
const ManagerUninstallBTCDep: CustomErrorFunc;
16
```
17

18
**Usage Examples:**
19

20
```typescript
21
import { 
22
  ManagerAppAlreadyInstalledError,
23
  ManagerAppRelyOnBTCError,
24
  ManagerAppDepInstallRequired,
25
  ManagerAppDepUninstallRequired,
26
  ManagerUninstallBTCDep
27
} from "@ledgerhq/errors";
28

29
// Handle app already installed
30
try {
31
  await installApp("Bitcoin");
32
} catch (error) {
33
  if (error instanceof ManagerAppAlreadyInstalledError) {
34
    console.log("Bitcoin app is already installed");
35
  }
36
}
37

38
// Handle Bitcoin dependency requirement
39
try {
40
  await installApp("BitcoinCash");
41
} catch (error) {
42
  if (error instanceof ManagerAppRelyOnBTCError) {
43
    console.log("Bitcoin Cash app requires Bitcoin app to be installed first");
44
  }
45
}
46

47
// Handle dependency install requirement
48
if (requiredDeps.length > 0) {
49
  throw new ManagerAppDepInstallRequired(
50
    `Please install dependencies first: ${requiredDeps.join(", ")}`
51
  );
52
}
53

54
// Handle dependency uninstall requirement
55
if (dependentApps.length > 0) {
56
  throw new ManagerAppDepUninstallRequired(
57
    `Please uninstall dependent apps first: ${dependentApps.join(", ")}`
58
  );
59
}
60

61
// Handle Bitcoin dependency uninstall
62
try {
63
  await uninstallApp("Bitcoin");
64
} catch (error) {
65
  if (error instanceof ManagerUninstallBTCDep) {
66
    console.log("Cannot uninstall Bitcoin - other apps depend on it");
67
  }
68
}
69
```
70

71
### Device Manager Errors
72

73
Errors related to device manager operations and device locking.
74

75
```typescript { .api }
76
const ManagerDeviceLockedError: CustomErrorFunc;
77
const ManagerNotEnoughSpaceError: CustomErrorFunc;
78
```
79

80
**Usage Examples:**
81

82
```typescript
83
import { 
84
  ManagerDeviceLockedError,
85
  ManagerNotEnoughSpaceError
86
} from "@ledgerhq/errors";
87

88
// Handle locked device during manager operations
89
try {
90
  await performManagerOperation();
91
} catch (error) {
92
  if (error instanceof ManagerDeviceLockedError) {
93
    console.log("Device is locked - please enter PIN and try again");
94
  }
95
}
96

97
// Handle insufficient storage space
98
function checkDeviceSpace(requiredSpace: number, availableSpace: number) {
99
  if (availableSpace < requiredSpace) {
100
    throw new ManagerNotEnoughSpaceError(
101
      `Insufficient space: ${requiredSpace}KB required, ${availableSpace}KB available`
102
    );
103
  }
104
}
105

106
// Example space management
107
async function installAppWithSpaceCheck(appName: string, appSize: number) {
108
  const deviceInfo = await getDeviceInfo();
109
  
110
  try {
111
    checkDeviceSpace(appSize, deviceInfo.availableSpace);
112
    await installApp(appName);
113
  } catch (error) {
114
    if (error instanceof ManagerNotEnoughSpaceError) {
115
      console.log("Please free up space by uninstalling unused apps");
116
      const suggestions = await getAppsToRemove(appSize);
117
      console.log("Consider removing:", suggestions.join(", "));
118
    }
119
  }
120
}
121
```
122

123
### Firmware Management Errors
124

125
Errors related to firmware updates and MCU operations.
126

127
```typescript { .api }
128
const FirmwareNotRecognized: CustomErrorFunc;
129
const FirmwareOrAppUpdateRequired: CustomErrorFunc;
130
const ManagerFirmwareNotEnoughSpaceError: CustomErrorFunc;
131
const LatestMCUInstalledError: CustomErrorFunc;
132
const UnknownMCU: CustomErrorFunc;
133
const UpdateFetchFileFail: CustomErrorFunc;
134
const UpdateIncorrectHash: CustomErrorFunc;
135
const UpdateIncorrectSig: CustomErrorFunc;
136
```
137

138
**Usage Examples:**
139

140
```typescript
141
import { 
142
  FirmwareNotRecognized,
143
  FirmwareOrAppUpdateRequired,
144
  ManagerFirmwareNotEnoughSpaceError,
145
  LatestMCUInstalledError,
146
  UnknownMCU
147
} from "@ledgerhq/errors";
148

149
// Handle unrecognized firmware
150
try {
151
  await validateFirmware();
152
} catch (error) {
153
  if (error instanceof FirmwareNotRecognized) {
154
    console.log("Device firmware is not recognized");
155
    console.log("Please contact support or update your device");
156
  }
157
}
158

159
// Handle required updates
160
function checkCompatibility(firmwareVersion: string, appVersion: string) {
161
  if (!isCompatible(firmwareVersion, appVersion)) {
162
    throw new FirmwareOrAppUpdateRequired(
163
      "Firmware or app update required for compatibility"
164
    );
165
  }
166
}
167

168
// Handle firmware space issues
169
try {
170
  await installFirmwareUpdate();
171
} catch (error) {
172
  if (error instanceof ManagerFirmwareNotEnoughSpaceError) {
173
    console.log("Insufficient space for firmware update");
174
    console.log("Please remove some apps and try again");
175
  }
176
}
177

178
// Handle MCU update attempts
179
try {
180
  await updateMCU();
181
} catch (error) {
182
  if (error instanceof LatestMCUInstalledError) {
183
    console.log("Latest MCU version is already installed");
184
  } else if (error instanceof UnknownMCU) {
185
    console.log("MCU type is not recognized");
186
  }
187
}
188

189
// Handle update file operations
190
try {
191
  const updateFile = await fetchUpdateFile(updateUrl);
192
} catch (error) {
193
  if (error instanceof UpdateFetchFileFail) {
194
    console.log("Failed to download update file - check network connection");
195
  }
196
}
197

198
// Handle update integrity validation
199
try {
200
  await validateUpdateFile(updateFile);
201
} catch (error) {
202
  if (error instanceof UpdateIncorrectHash) {
203
    console.log("Update file hash validation failed - file may be corrupted");
204
  } else if (error instanceof UpdateIncorrectSig) {
205
    console.log("Update file signature verification failed - file may be tampered");
206
  }
207
}
208
```
209

210
### Application Compatibility Errors
211

212
Errors related to application compatibility and requirements.
213

214
```typescript { .api }
215
const UpdateYourApp: CustomErrorFunc;
216
const DeviceAppVerifyNotSupported: CustomErrorFunc;
217
const BtcUnmatchedApp: CustomErrorFunc;
218
const WrongAppForCurrency: CustomErrorFunc;
219
```
220

221
**Usage Examples:**
222

223
```typescript
224
import { 
225
  UpdateYourApp,
226
  DeviceAppVerifyNotSupported,
227
  BtcUnmatchedApp,
228
  WrongAppForCurrency
229
} from "@ledgerhq/errors";
230

231
// Handle app update requirement
232
function checkAppVersion(currentVersion: string, requiredVersion: string) {
233
  if (isVersionOlder(currentVersion, requiredVersion)) {
234
    throw new UpdateYourApp(
235
      `Please update your app from ${currentVersion} to ${requiredVersion}`
236
    );
237
  }
238
}
239

240
// Handle unsupported verification
241
try {
242
  await verifyApp();
243
} catch (error) {
244
  if (error instanceof DeviceAppVerifyNotSupported) {
245
    console.log("App verification is not supported for this app version");
246
  }
247
}
248

249
// Handle Bitcoin app mismatch
250
function validateBitcoinOperation(openApp: string) {
251
  if (openApp !== "Bitcoin" && openApp !== "Bitcoin Test") {
252
    throw new BtcUnmatchedApp("Please open the Bitcoin app on your device");
253
  }
254
}
255

256
// Handle wrong app for currency
257
function validateCurrencyApp(currency: string, openApp: string) {
258
  const expectedApp = getCurrencyApp(currency);
259
  if (openApp !== expectedApp) {
260
    throw new WrongAppForCurrency(
261
      `Please open the ${expectedApp} app to handle ${currency} transactions`
262
    );
263
  }
264
}
265

266
// Example usage in transaction flow
267
async function prepareTransaction(currency: string, amount: number) {
268
  const deviceStatus = await getDeviceStatus();
269
  
270
  try {
271
    validateCurrencyApp(currency, deviceStatus.currentApp);
272
    await createTransaction(currency, amount);
273
  } catch (error) {
274
    if (error instanceof WrongAppForCurrency) {
275
      console.log("Please switch to the correct app on your device");
276
      await waitForAppSwitch();
277
      return prepareTransaction(currency, amount);
278
    }
279
  }
280
}
281
```