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.

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.