What causes "file-consent requires a configured tenant and App hook" in paperclipai/paperclip?

Set the Microsoft Teams tenant ID in configuration/env before constructing the runtime.

paperclipai/paperclip · error · TeamsAdapterCompatibilityError

file-consent requires a configured tenant and App hook

Error message

file-consent requires a configured tenant and App hook

What it means

Installing the Teams file-consent hook requires three things: an app object with an .on() hook method, a configured Microsoft Teams tenant ID (this.microsoftTeamsTenantId), and the provider being 'microsoft-teams'. If any precondition fails, this TeamsAdapterCompatibilityError is thrown because file-consent flows cannot be wired without them.

Source

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

      options.callbacks.onSlashCommand
    ) {
      installDiscordNativeCommands(
        this.adapter,
        this.chat,
        options.providerConfig.credentials.applicationId,
        options.providerConfig.credentials.guildId,
        this.discordCommandDispatch,
      );
    }
    if (this.teamsFileConsentEnabled) {
      const app = (this.adapter as unknown as TeamsAdapterInternals).app;
      if (
        !app ||
        typeof app.on !== "function" ||
        !this.microsoftTeamsTenantId ||
        options.providerConfig.provider !== "microsoft-teams"
      ) {
        throw new TeamsAdapterCompatibilityError(
          "file-consent requires a configured tenant and App hook",
        );
      }
      const callback = options.callbacks.onTeamsFileConsent!;
      installTeamsFileConsentHook(app as TeamsConsentApp, {
        companyId: this.companyId,
        endpointId: this.endpointId,
        tenantId: this.microsoftTeamsTenantId,
        botAppId: options.providerConfig.credentials.appId,
        onConsent: async (event) => {
          const attempt = this.webhookIngress.getStore();
          const promise = Promise.resolve().then(() =>
            callback({
              endpointId: this.endpointId,
              provider: this.provider,
              event,
            }),
          );

View on GitHub (pinned to 01ad858492)

Solutions

Set the Microsoft Teams tenant ID in configuration/env before constructing the runtime.
Enable the file-consent option only for provider 'microsoft-teams'.
Pass the initialized Chat SDK app (with a working .on() method) into the runtime options.
Verify adapter initialization order: app must exist before onTeamsFileConsent hook installation.

Example fix

// before
installFileConsent({ providerConfig: { provider: "telegram" }, callbacks: { onTeamsFileConsent } }); // wrong provider
// after
if (options.providerConfig.provider === "microsoft-teams" && process.env.MICROSOFT_TEAMS_TENANT_ID) {
  installFileConsent(options);
}

Defensive patterns

Strategy: validation

Validate before calling

const canInstallConsent = Boolean(app) && typeof app?.on === "function" &&
  Boolean(microsoftTeamsTenantId) && providerConfig.provider === "microsoft-teams";
if (!canInstallConsent) throw new Error("file-consent prerequisites missing");

Type guard

function canInstallFileConsent(app: unknown, tenantId: string | undefined, provider: string): boolean {
  return typeof app === "object" && app !== null && typeof (app as any).on === "function" &&
    typeof tenantId === "string" && tenantId.length > 0 && provider === "microsoft-teams";
}

Try / catch

try {
  runtime.installFileConsentHook();
} catch (err) {
  if (err instanceof TeamsAdapterCompatibilityError && /file-consent/.test(err.message)) {
    logger.error("file-consent skipped: set tenant ID and use the microsoft-teams provider");
    return;
  }
  throw err;
}

Prevention

Set the Teams tenant ID env/config before runtime construction.
Only enable onTeamsFileConsent callbacks for microsoft-teams provider.
Verify app.on exists before enabling consent features.

When it happens

Trigger: Enabling file-consent callbacks when: options.app is missing or lacks an on() function, this.microsoftTeamsTenantId is unset, or options.providerConfig.provider !== 'microsoft-teams'.

Common situations: MICROSOFT_TEAMS_TENANT_ID (or equivalent config) not set in the environment; file-consent enabled for a non-Teams provider; app object not yet initialized when hook installation runs; adapter instantiated before tenant configuration loads.

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/2b692142b26df219. Report an issue: GitHub.