paperclipai/paperclip · error · ToolGatewayHttpError

connector_profile_invalid

connector_profile_invalid

Error message

Managed authorization has an invalid connector profile

What it means

Managed authorization (managed OAuth) requires a valid connector profile id. The code accepts specific well-known profiles (e.g. "gmail.draft") or any profile passing isGoogleWorkspaceConnectorProfileId / isGitHubConnectorProfileId; otherwise it throws HTTP 422 'Managed authorization has an invalid connector profile' (code connector_profile_invalid) with connectionId and grantId context.

Solutions

1. Set the connector profile to a supported value (e.g. "gmail.draft") or a profile id accepted by isGoogleWorkspaceConnectorProfileId/isGitHubConnectorProfileId.
2. Log/inspect the connection's configuredProfile and fix the typo or casing.
3. Migrate old profile ids to the current naming if a version changed the validator.
4. Add the new provider/profile to the validators only if it is genuinely a supported managed profile.

Example fix

// before
const configuredProfile = connection.config.profile; // "gmai.draft"
// after
const configuredProfile = isGoogleWorkspaceConnectorProfileId(connection.config.profile) || isGitHubConnectorProfileId(connection.config.profile)
  ? connection.config.profile
  : "gmail.draft"; // fallback to a known-valid managed profile

import { isGoogleWorkspaceConnectorProfileId, isGitHubConnectorProfileId } from "@paperclipai/shared";
if (!(configuredProfile === "gmail.draft" || isGoogleWorkspaceConnectorProfileId(configuredProfile) || isGitHubConnectorProfileId(configuredProfile))) {
  throw new Error(`Invalid connector profile: ${configuredProfile}`);
}

function isValidConnectorProfile(p: unknown): p is string {
  return typeof p === "string" && (p === "gmail.draft" || isGoogleWorkspaceConnectorProfileId(p) || isGitHubConnectorProfileId(p));
}

try {
  await gateway.call(session, toolName, args);
} catch (e) {
  if (e instanceof ToolGatewayHttpError && e.code === "connector_profile_invalid") {
    // fix connection.config.profile to a supported managed profile and retry
  }
  throw e;
}

When it happens

Trigger: A connection/grant's configuredProfile is neither a recognized literal nor a valid Google Workspace or GitHub connector profile id — e.g. malformed string, profile id from an unsupported provider, empty/whitespace value, or a renamed profile id no longer matching the validators.

Common situations: Typo in a managed-authorization profile setting ("gmai.draft"); profile id copied from another integration (e.g. generic OAuth profile) that isn't in the Google/GitHub validator sets; schema/config drift after a version bump renamed profile ids.

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

• ACPX profile requires exact model ; received
• ACPX model must not be empty
• ACPX provider identity contains an invalid permission mode
• ACPX provider identity contains invalid lifetime fences
• / : oauth requires ownershipModes

AI-assisted analysis of paperclipai/paperclip@3f1d897a7c (2026-09-18). Data as JSON: /api/errors/2cd1afa6a79822c8. Report an issue: GitHub.

Appendix: source

Thrown at server/src/services/tool-gateway.ts:3579

    session: ToolGatewaySession,
    connection: typeof toolConnections.$inferSelect,
    grant: typeof connectionGrants.$inferSelect,
    forceRefresh = false,
  ): Promise<typeof connectionGrants.$inferSelect> {
    const oauth = asRecord(asRecord(connection.config)?.oauth);
    if (!oauth || !isPaperclipCloudConnectorStrategy(oauth.strategy))
      return grant;
    const configuredProfile = oauth.connectorProfile;
    const connectorProfile:
      GoogleWorkspaceConnectorProfileId | GitHubConnectorProfileId =
      configuredProfile === undefined
        ? "gmail.draft"
        : typeof configuredProfile === "string" &&
            (isGoogleWorkspaceConnectorProfileId(configuredProfile) ||
              isGitHubConnectorProfileId(configuredProfile))
          ? configuredProfile
          : (() => {
              throw new ToolGatewayHttpError(
                422,
                "Managed authorization has an invalid connector profile",
                "connector_profile_invalid",
                {
                  connectionId: connection.id,
                  grantId: grant.id,
                },
              );
            })();
    const connectorSubject =
      typeof oauth.connectorSubjectAgentId === "string"
        ? `agent:${oauth.connectorSubjectAgentId}`
        : typeof oauth.connectorSubjectUserId === "string"
          ? oauth.connectorSubjectUserId
          : grant.kind === "agent" && grant.subjectAgentId
            ? `agent:${grant.subjectAgentId}`
            : grant.subjectUserId;
    const grantOauth = asRecord(asRecord(grant.providerTenant)?.oauth);

View on GitHub (pinned to 3f1d897a7c)