immich-app/immich · error · Error

Failed to call host function "${String(name)}", received ${r

Error message

Failed to call host function "${String(name)}", received ${result.status} - ${JSON.stringify(result.message)}

What it means

Inside a plugin (WASM module loaded via extism), hostFunctions(authToken) wraps calls into the Immich host process. Each call serializes { authToken, args } to a memory pointer, invokes the host function, and parses the returned HostFunctionResult. When the host responds with { success: false, status, message } the wrapper throws an Error echoing the host HTTP status code and message. This is the plugin-side surface for any host rejection (auth, validation, not-found, server error).

Source

Thrown at packages/plugin-sdk/src/host-functions.ts:68

] as const;

export const hostFunctions = (authToken: string) => {
  const host = Host.getFunctions();
  type HostFunctionName = keyof typeof host;

  const call = <T, R>(name: HostFunctionName, authToken: string, args: T) => {
    const pointer1 = Memory.fromString(JSON.stringify({ authToken, args }));
    const fn = host[name];
    const handler = Memory.find(fn(pointer1.offset));

    try {
      const result = JSON.parse(handler.readString()) as HostFunctionResult<R>;

      if (result.success) {
        return result.response;
      }

      throw new Error(
        `Failed to call host function "${String(name)}", received ${result.status} - ${JSON.stringify(result.message)}`,
      );
    } finally {
      handler.free();
      pointer1.free();
    }
  };

  return {
    // album
    searchAlbums: (dto: AlbumSearchDto) =>
      call<[AlbumSearchDto], AlbumResponseDto[]>('searchAlbums', authToken, [
        dto,
      ]),
    createAlbum: (dto: CreateAlbumDto) =>
      call<[CreateAlbumDto], AlbumResponseDto>('createAlbum', authToken, [dto]),
    addAssetsToAlbum: (albumId: string, assetIds: string[]) =>
      call<[string, BulkIdsDto], BulkIdResponseDto[]>(

View on GitHub (pinned to 199723261c)

Solutions

1. Inspect the status/message embedded in the thrown error text to map it to the host-side cause (401 -> token, 404 -> missing resource, 4xx -> DTO, 5xx -> host fault).
2. Ensure the plugin is invoked with a valid, sufficiently-permissioned auth token for the operations it performs.
3. Validate DTOs (e.g. non-empty assetIds, existing albumId) before calling the host function.
4. For httpRequest, confirm the target URL is reachable and returns 2xx from the host network position.

Example fix

// before
const albums = host.searchAlbums({ albumName: 'x' }); // may throw
// after
try {
  const albums = host.searchAlbums({ albumName: 'x' });
} catch (e) {
  throw new Error(`album search failed in plugin: ${(e as Error).message}`);
}

// validate inputs before calling host functions
const assertNonEmpty = (v: unknown, name: string) => {
  if (!v || (Array.isArray(v) && v.length === 0))
    throw new Error(`${name} must be provided`);
};
assertNonEmpty(dto.albumName, 'albumName');

const isHostError = (e: unknown): e is Error =>
  e instanceof Error && e.message.startsWith('Failed to call host function');

try {
  const albums = host.searchAlbums(dto);
} catch (e) {
  if (isHostError(e)) {
    // parse status from message, degrade gracefully
    return [];
  }
  throw e;
}

When it happens

Trigger: Calling hostFunctions(token).searchAlbums(dto), createAlbum, addAssetsToAlbum, addAssetsToAlbums, or httpRequest when the authToken is invalid/expired, the DTO fails host-side validation, the album/asset does not exist, or the host returns any non-success status.

Common situations: Plugin runs with a stale or wrong-scoped auth token; the host Immich server is degraded; a deleted album/asset is referenced; an httpRequest to an external URL returns a non-2xx status.

Related errors

• authToken is required
• Calling host functions is not allowed without setting method
• The API key header can only be set using setApiKey().
• Missing JWT Token
• Invalid JWT Token

AI-assisted analysis of immich-app/immich@199723261c (2026-08-12). Data as JSON: /api/errors/0e8a47f90434141f. Report an issue: GitHub.