What causes "GitHub receipt runtime unavailable" in paperclipai/paperclip?

Verify the endpoint's chat provider is actually 'github' before invoking GitHub receipt mutations

GitHub receipt runtime unavailable

Error message

GitHub receipt runtime unavailable

What it means

applyGitHubReceiptReaction is a runtime-level wrapper that re-adds a GitHub receipt reaction using the GitHub App credential captured at runtime construction. The wrapper refuses to run unless the active chat provider is 'github' AND a githubReceiptApp (appId + installationId) was provided to the runtime; otherwise it throws 'GitHub receipt runtime unavailable'. It is a guard against calling a GitHub-specific mutation through a runtime configured for another provider or without receipt-apply credentials.

Source

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

      endpointId: this.endpointId,
      tenantId: this.microsoftTeamsTenantId,
      botAppId: this.microsoftTeamsAppId,
      runtimeGeneration: source.runtimeGeneration,
      credentialFingerprint: source.credentialFingerprint,
      threadId: source.threadId,
      messageId: source.messageId,
      principalExternalId: source.principalExternalId,
    };
  }

  /** Service-owned receipt action; no ordinary message or native status retry. */
  async applyGitHubReceiptReaction(
    input: GitHubReceiptMutation,
    assertCurrent: () => Promise<void>,
    fetchImpl?: typeof globalThis.fetch,
  ) {
    if (this.provider !== "github" || !this.githubReceiptApp)
      throw new Error("GitHub receipt runtime unavailable");
    return applyGitHubReceiptReaction(
      this.adapter,
      this.githubReceiptApp.appId,
      this.githubReceiptApp.installationId,
      input,
      assertCurrent,
      fetchImpl,
    );
  }

  async applySlackReceiptReaction(
    input: SlackReceiptMutation,
    fetchImpl?: typeof globalThis.fetch,
  ): Promise<void> {
    if (this.provider !== "slack" || !this.slackReceiptBotToken)
      throw new Error("Slack receipt runtime unavailable");
    await applySlackReceiptReaction(
      { ...input, botToken: this.slackReceiptBotToken },

View on GitHub (pinned to 01ad858492)

Solutions

Verify the endpoint's chat provider is actually 'github' before invoking GitHub receipt mutations
Configure the GitHub receipt App (appId + installationId) when constructing the ChatSdkRuntime so this.githubReceiptApp is populated
Check environment/config loading for the GitHub App credentials; reinstall the GitHub App installation if it was removed
Route the receipt mutation to the runtime instance matching the provider instead of the current one

Example fix

// before
await runtime.applyGitHubReceiptReaction(input, assertCurrent);
// after
if (runtime.provider === 'github') {
  await runtime.applyGitHubReceiptReaction(input, assertCurrent);
}

Defensive patterns

Strategy: validation

Validate before calling

if (runtime.provider !== 'github') throw new Error('GitHub receipt requires a github runtime');

Type guard

const canApplyGitHubReceipt = (r: ChatSdkRuntime): r is ChatSdkRuntime & { provider: 'github' } => r.provider === 'github';

Try / catch

try { await runtime.applyGitHubReceiptReaction(input, assertCurrent); } catch (e) { if ((e as Error).message === 'GitHub receipt runtime unavailable') { /* route to correct provider runtime or log config gap */ } else throw e; }

Prevention

Match receipt mutations to the runtime provider before dispatching
Provision GitHub App appId/installationId whenever GitHub receipt endpoints are created
Add a startup check that fails fast if a github endpoint lacks receipt credentials

When it happens

Trigger: Calling applyGitHubReceiptReaction when (a) this.provider !== 'github' (runtime built for slack/telegram/teams), or (b) this.githubReceiptApp is null because no GitHub App appId/installationId was supplied at runtime construction.

Common situations: Endpoint misconfiguration where the receipt pipeline is wired to a GitHub receipt store but the chat endpoint is Slack/Teams; missing GitHub App installation env/config (PAPERCLIP GitHub app not installed for the org); stale runtime instances created before the GitHub App was configured.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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