> For the complete documentation index, see [llms.txt](https://docs.jetadmin.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.jetadmin.io/api-reference/javascript-sdk/troubleshooting.md).

# Errors and troubleshooting

### Handle request errors

Axios requests are wrapped in `JetRequestError`. Agent streaming also throws this error for HTTP, content-type, and explicit server error events, but native fetch and JSON parsing errors can propagate separately.

```typescript
import { Jet, JetRequestError } from '@jet-admin/jet-sdk';

async function loadRecords(jet: Jet) {
  try {
    return await jet.collection('YOUR_RESOURCE', 'YOUR_COLLECTION').list();
  } catch (error) {
    if (error instanceof JetRequestError) {
      return {
        error: error.message,
        fields: error.fieldErrors,
        status: error.status,
      };
    }
    throw error;
  }
}
```

| Property         | Meaning                                                                                    |
| ---------------- | ------------------------------------------------------------------------------------------ |
| `message`        | First parsed error message                                                                 |
| `nonFieldErrors` | General errors                                                                             |
| `fieldErrors`    | Field-name-to-message mapping                                                              |
| `errors`         | General and field errors combined                                                          |
| `status`         | HTTP status for Axios errors when available; may be absent for network or streaming errors |
| `originalError`  | Underlying error; may contain request details                                              |
| `response`       | Underlying Axios error for Axios failures, despite the property name                       |

`serialize()` returns JSON containing `nonFieldErrors` and `fieldErrors`. Avoid logging full request errors or their underlying Axios objects where tokens or user data could be exposed.

### Common issues

| Symptom                                       | What to check                                                                                                                       |
| --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `localStorage is not defined`                 | Initialize in the browser. This version has no server-safe storage adapter.                                                         |
| Browser denies storage access                 | The constructor calls storage directly; allow storage in that context before initialization.                                        |
| Request URL includes `undefined`              | Set `project`; it has no default or constructor validation.                                                                         |
| 401/403                                       | Check user permissions, project/environment, token validity, and token-prefix compatibility. `apiToken` overrides a logged-in user. |
| Fields seem missing from records              | Read `record.data`, not `record.name`.                                                                                              |
| Logging out still sends a token               | A configured `apiToken` persists; discard that client. Other client instances may also retain user state.                           |
| Unexpected account across projects            | All browser clients share the `jet_auth` storage key.                                                                               |
| Filters are ignored                           | Confirm resource-specific field names, supported lookup suffixes, and array serialization.                                          |
| Storage upload fails in a server runtime      | The implementation uses `File`, `Blob`, and `FormData`, plus authentication storage.                                                |
| Workflow promise resolves but operation fails | Check `response.success` and `response.error`.                                                                                      |
| A stream produces no messages                 | Verify the endpoint returns `text/event-stream` and events supported by this SDK.                                                   |

### Streaming limitations

The current parser splits frames on `\n\n` and keeps one `data:` line per frame. It does not implement all SSE framing rules: CRLF-separated frames, multiline data, and an unfinished final frame can be mishandled. There is no automatic reconnect. If these issues affect your endpoint, use `prompt()` for a non-streamed response while the parser is corrected.

### Retries, timeouts, and limits

The SDK defines no automatic retry policy, rate-limit handling, or configurable timeout option in `JetOptions`. Server limits and resource capabilities are not specified by this repository. Avoid retrying writes, actions, or workflows automatically unless your operation is safe to repeat.

These guides are based on source inspection. Live authentication, permissions, and backend responses must be checked against your project's deployment.


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.jetadmin.io/api-reference/javascript-sdk/troubleshooting.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.