{"record":{"id":"a2e20f648250cf81","repo":"paperclipai/paperclip","slug":"chat-sdk-webhook-handler-is-unavailable-for-this","errorCode":null,"errorMessage":"Chat SDK webhook handler is unavailable for ${this.provider}","messagePattern":"Chat SDK webhook handler is unavailable for (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/src/services/chat-sdk-runtime.ts","lineNumber":2352,"sourceCode":"  async handleWebhook(\n    request: Request,\n    options?: WebhookOptions,\n    responseDeadlineAt?: number,\n    serviceReceivedAtMs?: number,\n  ): Promise<Response> {\n    this.assertNotRetired();\n    // A body read, identity initialization or durable queue wait cannot mint\n    // a fresh provider response window for an already received callback.\n    const runtimeReceivedAtMs = Date.now();\n    const receivedAtMs =\n      typeof serviceReceivedAtMs === \"number\" &&\n      Number.isSafeInteger(serviceReceivedAtMs) &&\n      serviceReceivedAtMs > 0\n        ? Math.min(serviceReceivedAtMs, runtimeReceivedAtMs)\n        : runtimeReceivedAtMs;\n    const handler = this.chat.webhooks[this.sdkAdapterKey];\n    if (!handler) {\n      throw new Error(\n        `Chat SDK webhook handler is unavailable for ${this.provider}`,\n      );\n    }\n    const providerUpdateId =\n      this.provider === \"telegram\"\n        ? await telegramWebhookUpdateId(request)\n        : undefined;\n    const attempt: WebhookIngressAttempt = {\n      receivedAtMs,\n      callbackError: undefined,\n      callbackPromises: new Set(),\n      ...(providerUpdateId !== undefined ? { providerUpdateId } : {}),\n    };\n    const sdkTasks: Promise<unknown>[] = [];\n    const deadlineAt = Math.min(\n      Date.now() + this.webhookIngressTimeoutMs,\n      responseDeadlineAt ?? Number.POSITIVE_INFINITY,\n    );","sourceCodeStart":2334,"sourceCodeEnd":2370,"githubUrl":"https://github.com/paperclipai/paperclip/blob/01ad8584922b5d85292b1723cae71fa0d9b07a19/server/src/services/chat-sdk-runtime.ts#L2334-L2370","documentation":"Each Chat SDK provider must register a webhook handler under chat.webhooks[sdkAdapterKey]. When an inbound webhook arrives for a provider whose handler was never registered (chat.webhooks[this.sdkAdapterKey] is falsy), the runtime throws this error naming the provider.","triggerScenarios":"POSTing a webhook update to the endpoint for a provider whose adapter was not registered in chat.webhooks — e.g. sdkAdapterKey mismatch, adapter not initialized, or webhook route enabled for a provider the runtime doesn't support.","commonSituations":"Env/config enables a provider's webhook but the adapter failed to initialize earlier (swallowing an init error); SDK upgrade changed the adapter key; provider string and adapter key out of sync; starting webhook routes before chat.initialize() completes.","solutions":["Ensure chat.initialize() completes before webhook routes accept traffic.","Confirm the adapter registers itself under the expected sdkAdapterKey in chat.webhooks.","Check startup logs for adapter initialization failures that left the webhook map empty.","Align the provider name in webhook route config with the registered SDK adapter key."],"exampleFix":"// before\napp.post(\"/webhooks/telegram\", handler); // adapter never registered\n// after\nawait chat.initialize();\nif (!chat.webhooks[telegramSdkAdapterKey]) {\n  throw new Error(\"telegram adapter failed to register its webhook handler\");\n}\napp.post(\"/webhooks/telegram\", handler);","handlingStrategy":"try-catch","validationCode":"await chat.initialize();\nconst handler = chat.webhooks[sdkAdapterKey];\nif (!handler) throw new Error(`no webhook handler registered for key ${sdkAdapterKey}`);","typeGuard":"null","tryCatchPattern":"try {\n  await runtime.handleWebhook(request, runtimeReceivedAtMs);\n} catch (err) {\n  if (/webhook handler is unavailable/.test(String(err?.message))) {\n    logger.error({ provider: runtime.provider }, \"provider adapter not registered; check initialization and adapter key\");\n  }\n  throw err;\n}","preventionTips":["Complete chat.initialize() before accepting webhook traffic.","Fail fast at startup if chat.webhooks lacks expected provider keys.","Keep provider names and sdkAdapterKey values aligned in config.","Watch for swallowed adapter init errors that leave the webhook map empty."],"tags":["webhook","provider","initialization"],"backgroundTag":"resource-not-found","analyzedSha":"01ad8584922b5d85292b1723cae71fa0d9b07a19","analyzedAt":"2026-09-10T03:14:50.855Z","contentChangedAt":"2026-09-10T03:14:50.855Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}