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.

Source

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

  }

  async function maybeRefreshPaperclipCloudGrant(
    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);
    const expiresAt = typeof grantOauth?.accessTokenExpiresAt === "string"
      ? Date.parse(grantOauth.accessTokenExpiresAt)
      : Number.NaN;
    const currentTime = options.now?.() ?? Date.now();
    // The preferred GitHub App policy yields a non-expiring ghu_ token and no
    // refresh token. Absence of an expiry is deliberate, not an invitation to

View on GitHub (pinned to 01ad858492)

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

• ${label} is not a regular file at ${canonical}.
• Claude Managed evals require exact model claude-sonnet-5
• AWS AgentCore evals require exact model global.anthropic.cla
• request.session.provider must match request.provider
• request.session.requestedModel must match request.model

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