What causes "Telegram authenticated dispatch contract is unavailable" in paperclipai/paperclip?

Ensure the adapter registered for provider 'telegram' is the real Telegram adapter exposing processUpdate.

Telegram authenticated dispatch contract is unavailable

Error message

Telegram authenticated dispatch contract is unavailable

What it means

For Telegram, authenticated webhook dispatch relies on the adapter exposing processUpdate(update, options). Before the runtime wraps processUpdate with its pinned webhook verifier, it asserts the method exists on the adapter; if not, this error is thrown, indicating the adapter does not fulfill the authenticated dispatch contract.

Source

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

      1,
      Math.min(options.webhookIngressTimeoutMs ?? 2_500, 10_000),
    );
    this.adapter = createProviderAdapter(
      options.providerConfig,
      options.logger,
      options.callbacks,
      options.endpointId,
      (fatal) => {
        this.discordGatewayFatal = fatal;
      },
    );
    if (this.provider === "telegram") {
      const adapter = this.adapter as unknown as {
        botUserId?: string;
        processUpdate(update: unknown, options?: WebhookOptions): void;
      };
      if (typeof adapter.processUpdate !== "function") {
        throw new Error(
          "Telegram authenticated dispatch contract is unavailable",
        );
      }
      const processUpdate = adapter.processUpdate.bind(this.adapter);
      adapter.processUpdate = (update, webhookOptions) => {
        // The pinned webhook verifier calls processUpdate only after checking
        // the secret. No parser-normalized chat:0 input may enter ordinary work.
        if (hasTelegramEphemeralInput(update)) return;
        const attempt = this.webhookIngress.getStore();
        if (isRecord(update) && "stopped_message_generation" in update) {
          // This wrapper is reached only after the pinned webhook secret check.
          // Join the durable callback to the same HTTP acknowledgement barrier.
          const proof =
            attempt && adapter.botUserId
              ? captureTelegramGenerationStopped(adapter.botUserId, update)
              : null;
          if (proof && options.callbacks.onTelegramGenerationStopped) {
            const task = Promise.resolve().then(() =>

View on GitHub (pinned to 01ad858492)

Solutions

Ensure the adapter registered for provider 'telegram' is the real Telegram adapter exposing processUpdate.
Upgrade/repair the adapter package to a version that includes processUpdate.
Check adapter registration/config so the provider name matches the adapter class actually instantiated.
If using a custom adapter, implement processUpdate(update: unknown, options?: WebhookOptions): void.

Example fix

// before
this.adapter = new GenericPollingAdapter(); // no processUpdate
// after
this.adapter = new TelegramAdapter(); // exposes processUpdate(update, options)

Defensive patterns

Strategy: type-guard

Validate before calling

const a = adapter as { processUpdate?: unknown };
if (typeof a.processUpdate !== "function") {
  throw new Error("registered telegram adapter lacks processUpdate");
}

Type guard

function hasProcessUpdate(a: unknown): a is { processUpdate(update: unknown, options?: unknown): void } {
  return typeof a === "object" && a !== null && typeof (a as any).processUpdate === "function";
}

Try / catch

try {
  telegramRuntime.startWebhook();
} catch (err) {
  if (/authenticated dispatch contract/.test(String(err?.message))) {
    logger.error("telegram adapter missing processUpdate; check adapter registration");
  }
  throw err;
}

Prevention

Register the real Telegram adapter for provider 'telegram', not a generic base class.
Check processUpdate presence in an adapter smoke test.
Keep adapter and runtime versions in lockstep.

When it happens

Trigger: Starting the Telegram webhook path where adapter.processUpdate is undefined or not a function — e.g. the adapter object lacks the method or is the wrong class entirely.

Common situations: Swapped/legacy adapter implementation without processUpdate; adapter upgrade where the method was renamed; misconfiguration causing a base adapter (not the Telegram one) to be registered under provider 'telegram'; tree-shaken/bundled builds dropping the method.

Understand the failure class

Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

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