> For the complete documentation index, see [llms.txt](https://docs.blynk.io/en/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.blynk.io/en/html-widget-developer-guide/errors-logging-and-cleanup.md).

# Errors, Logging & Cleanup

### BlynkBridgeError

Every request method rejects with a `BlynkBridgeError`, exposed on `window` by both hosts:

```ts
class BlynkBridgeError extends Error {
  name:    'BlynkBridgeError';
  code:    string;    // stable, machine-readable — branch on this
  message: string;    // human-readable — can change, never branch on it
  details: object;    // extra context, e.g. { index, count } or { selector, indexes }
}
```

```js
try {
  await bridge.getDeviceMetadata({ id: 42 });
} catch (error) {
  if (error instanceof window.BlynkBridgeError) {
    bridge.log(error.code + ' ' + JSON.stringify(error.details));
  }
}

// A tolerant helper for catch blocks
const codeOf = (error) => (error && typeof error.code === 'string') ? error.code : 'unknown';
```

**Codes shared by every request**

| Code                 | When                                                       |
| -------------------- | ---------------------------------------------------------- |
| `device_unavailable` | Called outside a Blynk host, or the host lacks that bridge |
| `bridge_destroyed`   | Called after `destroy()`                                   |
| `invalid_request`    | Arguments failed validation                                |
| `request_timeout`    | No answer in time — see below                              |
| `server_error`       | The host failed without a specific code                    |

Each method's own codes are listed in its entry.

**Errors usually arrive twice.** Every failing request reports its message through `sendError` — so your `onError` runs — **before** the Promise rejects. In `.catch()`, update widget state only ("--", "Could not load data"); don't show a second message. The Promise still rejects when error notifications are disabled.

**Request timeouts (web)**

| Requests                                                                                                               | Timeout |
| ---------------------------------------------------------------------------------------------------------------------- | ------- |
| `getDeviceInfo`, `getTheme`, `getUnitSystems`, `isPermissionAllowed`, storage, native screens                          | 10 s    |
| `getHistoricalData`, `getMapData`, events, device metadata, `getDeviceTags`, file and asset lists, records and deletes | 30 s    |
| `executeDataEngineQuery`                                                                                               | 35 s    |
| `getDeviceFileBlob`, `getAssetBlob`, `uploadDeviceFile`                                                                | 120 s   |

On mobile, history and map data also time out after 30 seconds and Data Engine queries after 35 seconds. Other mobile requests are bounded by the app.

***

### Report an error

> Shows an error in the host UI and passes it to your own `onError`.

```js
bridge.sendError(message)  // → void
```

| Name      | Type     | Required | Description             |
| --------- | -------- | -------- | ----------------------- |
| `message` | `string` | yes      | Non-empty error message |

* **Web:** the message is posted to the dashboard, which shows it as the widget's runtime error.
* **Mobile:** the app shows it as a toast.
* It does nothing when `message` is empty or not a string, or when `isOnErrorEnabled` is `false`.

```js
fetch('https://api.example.com/data')
  .then(r => r.json())
  .then(renderData)
  .catch(err => bridge.sendError('Data fetch failed: ' + err));
```

### Turn error reporting on or off

> Suppresses or re-enables both `sendError()` and the `onError` callback.

```js
bridge.setOnErrorEnabled(enabled)  // → void
```

| Name      | Type      | Required | Description                                                      |
| --------- | --------- | -------- | ---------------------------------------------------------------- |
| `enabled` | `boolean` | yes      | `false` silences error reporting; `true` (default) re-enables it |

***

### Log a message

> Forwards a message to the Blynk platform logger.

```js
bridge.log(message)          // → void
bridge.setLogging(enabled)   // → void — false silences bridge.log()
```

`setLogging(false)` turns off logging only, not error delivery.

***

### Destroy the bridge

> Detaches the bridge when your UI is removed.

```js
bridge.destroy()  // → void
```

* Clears all six callbacks and removes the host handlers this instance owns (on mobile, the `window.blynk*` functions it installed).
* Afterwards every Promise-returning method rejects with `bridge_destroyed`, and `sendValue`, `sendError` and dashboard-page navigation do nothing. Create a new `BlynkBridge` to use the bridge again.
* Repeated calls are safe, and destroying an old instance doesn't disturb a newer one's handlers.
* It doesn't abort requests or writes already in flight.
* Use `setCallbacks` to change handlers and `destroy()` when your UI goes away — never replace the bridge globals by hand.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.blynk.io/en/html-widget-developer-guide/errors-logging-and-cleanup.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
