paperclipai/paperclip · error

Telegram attachment parser contract is unavailable

Error message

Telegram attachment parser contract is unavailable

What it means

The Telegram attachment path relies on the adapter exposing three functions: extractAttachments, createAttachment, and parseTelegramMessage. When the loaded parser object is missing any of these methods, the runtime throws this error because it cannot honor the Telegram attachment parser contract.

Source

Thrown at server/src/services/chat-sdk-runtime.ts:1494

      const parser = adapter as unknown as {
        extractAttachments(raw: TelegramRawMessage): Attachment[];
        parseTelegramMessage(
          raw: TelegramRawMessage,
          threadId: string,
          content?: { text: string; formatted: Message["formatted"] },
        ): Message;
        createAttachment(
          type: Attachment["type"],
          fileId: string,
          metadata: Record<string, unknown>,
        ): Attachment;
      };
      if (
        typeof parser.extractAttachments !== "function" ||
        typeof parser.createAttachment !== "function" ||
        typeof parser.parseTelegramMessage !== "function"
      ) {
        throw new Error("Telegram attachment parser contract is unavailable");
      }
      const extractAttachments = parser.extractAttachments.bind(adapter);
      const create = (
        type: Attachment["type"],
        fileId: string,
        metadata: Record<string, unknown>,
      ) => parser.createAttachment(type, fileId, metadata);
      parser.extractAttachments = (raw) =>
        normalizeTelegramRichMessage(raw, create)?.attachments ??
        normalizeTelegramMediaAttachments(
          raw,
          normalizeTelegramVideoNoteAttachments(raw, extractAttachments(raw)),
          create,
        );
      const parseTelegramMessage = parser.parseTelegramMessage.bind(adapter);
      parser.parseTelegramMessage = (raw, threadId, content) => {
        const rich = normalizeTelegramRichMessage(raw, create);
        if (!rich) return parseTelegramMessage(raw, threadId, content);

View on GitHub (pinned to 01ad858492)

Solutions

1. Reinstall/upgrade the Telegram adapter package so the full parser surface (extractAttachments, createAttachment, parseTelegramMessage) is present.
2. Check the adapter version against the runtime's expectations; pin a compatible version.
3. If using a custom adapter, implement all three parser methods with the expected signatures.
4. Log the parser object at startup and assert the three methods exist as part of a smoke test.

Example fix

// before
const parser = require("telegram-adapter-lite").parser; // missing parseTelegramMessage
// after
const parser = require("@paperclipai/telegram-adapter").parser;
for (const m of ["extractAttachments", "createAttachment", "parseTelegramMessage"] as const) {
  if (typeof parser[m] !== "function") throw new Error(`parser missing ${m}`);
}

function hasTelegramParser(p: unknown): p is { extractAttachments: Function; createAttachment: Function; parseTelegramMessage: Function } {
  return typeof p === "object" && p !== null &&
    ["extractAttachments", "createAttachment", "parseTelegramMessage"].every(
      (m) => typeof (p as any)[m] === "function");
}

function hasTelegramParser(p: unknown): p is { extractAttachments: Function; createAttachment: Function; parseTelegramMessage: Function } {
  return typeof p === "object" && p !== null &&
    typeof (p as any).extractAttachments === "function" &&
    typeof (p as any).createAttachment === "function" &&
    typeof (p as any).parseTelegramMessage === "function";
}

try {
  await telegramRuntime.start();
} catch (err) {
  if (/parser contract/.test(String(err?.message))) {
    logger.error("Telegram adapter missing attachment parser; reinstall/upgrade the adapter package");
  }
  throw err;
}

When it happens

Trigger: Initializing/using the Telegram runtime where the adapter object's parser lacks extractAttachments, createAttachment, or parseTelegramMessage as functions.

Common situations: Downgraded or partially installed adapter package; adapter version drift where parser methods were renamed/removed; custom adapter builds missing the attachment parser module; dependency resolution pulling a stub implementation.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

• Adapter declares unsupported UI parser contract version — sk
• UI parser path escapes package directory — skipping
• ${prefix}: the capability must be an object.
• ${prefix}: "panelMode" must be one of ${ADAPTER_LOGIN_PANEL_
• ${prefix}: "sandboxTransport" must be one of ${ADAPTER_LOGIN

AI-assisted analysis of paperclipai/paperclip@01ad858492 (2026-09-10). Data as JSON: /api/errors/0783f15e318f18bb. Report an issue: GitHub.