GitHub inventory failed: this chat connection requires a ded

Error message

GitHub inventory failed: this chat connection requires a dedicated GitHub App with exactly one active installation

What it means

discoverDedicatedGitHubAppInstallation resolves the single active GitHub App installation backing a chat provider connection. This error is thrown when the GitHub App has more than one active installation, because the inventory feature requires a dedicated app installed on exactly one account/repo set so installation id and account can be resolved unambiguously.

Source

Thrown at server/src/services/chat-provider-inventory.ts:303

        account?: { id?: number; login?: string; name?: string; type?: string };
        permissions?: Record<string, string>;
        suspended_at?: string | null;
      }>
    >(response, "GitHub");
    installations.push(...pageInstallations);
    if (pageInstallations.length < 100) break;
  }
  const active = installations.filter(
    (installation) =>
      Number.isFinite(installation.id) && !installation.suspended_at,
  );
  if (active.length === 0) {
    throw new Error(
      "GitHub inventory failed: install this GitHub App on the selected repositories first",
    );
  }
  if (active.length !== 1) {
    throw new Error(
      "GitHub inventory failed: this chat connection requires a dedicated GitHub App with exactly one active installation",
    );
  }
  const installation = active[0]!;
  const missingPermissions = Object.entries(
    REQUIRED_GITHUB_INSTALLATION_PERMISSIONS,
  )
    .filter(
      ([permission, access]) =>
        installation.permissions?.[permission] !== access,
    )
    .map(([permission]) => permission);
  if (missingPermissions.length > 0) {
    throw new Error(
      `GitHub inventory failed: the active installation has not granted the required access for: ${missingPermissions.join(", ")}. Approve the GitHub App permission update, then retry`,
    );
  }
  return {

View on GitHub (pinned to 01ad858492)

Solutions

Uninstall the GitHub App from all but the one intended account/repo set, then retry inventory discovery.
Create a dedicated (new) GitHub App used only for this chat connection and install it on exactly the target repositories.
Point the chat connection's GitHub App credentials at an app that has only one installation.
If org-wide plus per-repo installs exist, remove the duplicate and keep a single installation scoped to the selected repositories.

Example fix

// before: shared app installed on org A and org B
// GitHub App installations: [{account: 'org-a'}, {account: 'org-b'}] -> throws
// after: uninstall from org-b, leaving exactly one active installation
// GitHub App installations: [{account: 'org-a'}] -> resolves

Defensive patterns

Strategy: validation

Validate before calling

const installs = await listAppInstallations(octokit);
if (installs.filter(i => i.suspended_at === null).length !== 1) {
  throw new Error("Dedicated GitHub App must have exactly one active installation");
}

Type guard

function hasSingleActiveInstallation(installs: { suspended_at: string | null }[]): boolean {
  return installs.filter(i => i.suspended_at === null).length === 1;
}

Try / catch

try {
  await discoverDedicatedGitHubAppInstallation(conn);
} catch (e) {
  if (e.message.includes("exactly one active installation")) {
    // surface guidance: uninstall duplicate installations or use a dedicated app
  }
}

Prevention

Use one dedicated GitHub App per chat connection, never a shared multi-org app.
Before discovery, list installations via the app JWT and assert exactly one active one.
Document that org-wide plus per-repo installs count as multiple installations.
Alert when the app gains a second installation in GitHub settings.

When it happens

Trigger: Calling the GitHub chat-provider inventory flow (which invokes discoverDedicatedGitHubAppInstallation at server/src/services/chat-provider-inventory.ts:303) while the same GitHub App is installed on two or more accounts or installed both org-wide and per-repo, yielding active.length !== 1.

Common situations: A shared/internal GitHub App reused across multiple orgs; an admin installing the app org-wide while a teammate also installed it on a personal account; switching the connection to an app that already serves other repositories.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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