Global settings and errors

@adt/fmdapi exports one global setting and two dedicated error classes. Most applications only need the error classes at a shared error boundary.

Set the Web Viewer name

globalSettings.setWebViewerName() is retained as a no-op for apps scaffolded before ADT 0.8:

import { globalSettings } from "@adt/fmdapi";

globalSettings.setWebViewerName("web");

Older fmFetch calls needed this to know which Web Viewer object should receive a script's callback. fmFetch no longer works that way — it calls the script directly and reads its Exit Script result — so this call does nothing. It's kept only so apps written against the old flow keep compiling; new code should not call it. See Script Calls for how fmFetch works now.

Handle FileMaker Data API errors

WebViewerAdapter throws FileMakerError when FileMaker returns a non-zero Data API error code.

import { FileMakerError } from "@adt/fmdapi";

try {
  await ContactsLayout.find({ query: { Status: "Active" } });
} catch (error) {
  if (error instanceof FileMakerError) {
    console.error(`FileMaker error ${error.code}: ${error.message}`);
  }
}

FileMakerError

The code comes from the first item in the Data API response's messages array. If the response does not contain a code, the adapter uses "500".

An empty find can produce FileMaker error 401. When no match is an expected result, use maybeFindFirst() or the method's ignoreEmptyResult option instead of treating it as an application failure. See Record methods and pagination for each method's empty-result behavior.

Handle an upload timeout

containerUpload() throws ContainerUploadTimeoutError when its FileMaker script does not call back before the configured timeout.

import { ContainerUploadTimeoutError } from "@adt/fmdapi";

try {
  await ContactsLayout.containerUpload({
    recordId: "42",
    fieldName: "Photo",
    file,
  });
} catch (error) {
  if (error instanceof ContainerUploadTimeoutError) {
    console.warn(
      `${error.scriptName} did not respond within ${error.timeoutMs}ms`,
    );
  }
}

ContainerUploadTimeoutError

Do not retry automatically. Check the target record before trying again because the first upload may have completed. See containerUpload() and WebViewerAdapter container settings.

Handle other errors

Errors without a dedicated class use the standard JavaScript Error class. These include:

• A list or find limit below 1.

• A method that expects one record receiving no records or more than one record.

• Schema validation failures. The client also writes the validation issues to console.error.

• A missing window.FileMaker bridge when a script call starts.

• Invalid container-upload input, such as a file without an extension, an unsupported repetition, or a file larger than the configured limit.

• A missing or malformed response from the FileMaker batch script.

Handle the dedicated classes first, then use a final fallback for standard errors and unexpected values:

import {
  ContainerUploadTimeoutError,
  FileMakerError,
} from "@adt/fmdapi";

try {
  await runFileMakerWork();
} catch (error) {
  if (error instanceof FileMakerError) {
    handleFileMakerError(error.code, error.message);
  } else if (error instanceof ContainerUploadTimeoutError) {
    await checkWhetherUploadCompleted();
  } else if (error instanceof Error) {
    reportUnexpectedError(error);
  } else {
    reportUnexpectedError(new Error(String(error)));
  }
}

Do not depend on the exact message text of a standard Error. Use the dedicated error classes where available, and treat other messages as diagnostic information.