gravitational/teleport · error

unknown integration subkind: %s

Error message

unknown integration subkind: %s

What it means

This error is returned by getIntegrationMetadata in Teleport's integration service when an Integration resource has a SubKind that the metadata builder does not recognize. The switch statement maps known integration subkinds (e.g. AWS OIDC, AWS Roles Anywhere) to their event metadata structs; any other subkind falls into the default branch. It indicates a subkind was added to the types package but not to this metadata mapping, or a client supplied an invalid/unsupported subkind.

Source

Thrown at lib/auth/integration/integrationv1/service.go:489

		igMeta.AWSOIDC = &apievents.AWSOIDCIntegrationMetadata{
			RoleARN:     ig.GetAWSOIDCIntegrationSpec().RoleARN,
			IssuerS3URI: ig.GetAWSOIDCIntegrationSpec().IssuerS3URI,
		}
	case types.IntegrationSubKindAzureOIDC:
		igMeta.AzureOIDC = &apievents.AzureOIDCIntegrationMetadata{
			TenantID: ig.GetAzureOIDCIntegrationSpec().TenantID,
			ClientID: ig.GetAzureOIDCIntegrationSpec().ClientID,
		}
	case types.IntegrationSubKindGitHub:
		igMeta.GitHub = &apievents.GitHubIntegrationMetadata{
			Organization: ig.GetGitHubIntegrationSpec().Organization,
		}
	case types.IntegrationSubKindAWSRolesAnywhere:
		igMeta.AWSRA = &apievents.AWSRAIntegrationMetadata{
			TrustAnchorARN: ig.GetAWSRolesAnywhereIntegrationSpec().TrustAnchorARN,
		}
	default:
		return apievents.IntegrationMetadata{}, fmt.Errorf("unknown integration subkind: %s", igMeta.SubKind)
	}

	return igMeta, nil
}

// DeleteAllIntegrations removes all Integration resources.
// DEPRECATED: can't delete all integrations over gRPC.
func (s *Service) DeleteAllIntegrations(ctx context.Context, _ *integrationpb.DeleteAllIntegrationsRequest) (*emptypb.Empty, error) {
	return nil, trace.BadParameter("DeleteAllIntegrations is deprecated")
}

func (s *Service) ensureNoAssociatedResources(ctx context.Context, ig types.Integration) error {
	switch ig.GetSubKind() {
	case types.IntegrationSubKindGitHub:
		return trace.Wrap(s.ensureNoGitHubAssociatedResources(ctx, ig))
	default:
		// TODO support this check for other types.
		return nil

View on GitHub (pinned to 1283425b60)

Solutions

1. Check the Integration resource's spec.sub_kind for typos or unsupported values and correct it to a valid subkind (e.g. aws-oidc, aws-roles-anywhere).
2. Upgrade all Teleport components (auth server, proxies) to the same version so newly introduced subkinds are recognized.
3. If you are adding a new integration subkind in code, add a case for types.IntegrationSubKind<New> in getIntegrationMetadata that populates the corresponding apievents metadata struct.
4. Verify no stale/corrupt integration resources exist in the backend (tctl get integrations) and delete invalid ones.

Example fix

// before (new subkind added in types but no case here)
case types.IntegrationSubKindAWSRolesAnywhere:
    ...
default:
    return apievents.IntegrationMetadata{}, fmt.Errorf("unknown integration subkind: %s", igMeta.SubKind)
// after
case types.IntegrationSubKindAWSRolesAnywhere:
    ...
case types.IntegrationSubKindMyNewKind:
    igMeta.MyNew = &apievents.MyNewIntegrationMetadata{ ... }
default:
    return apievents.IntegrationMetadata{}, fmt.Errorf("unknown integration subkind: %s", igMeta.SubKind)

const knownSubkinds = map[string]bool{"aws-oidc": true, "aws-roles-anywhere": true}
if !knownSubkinds[ig.GetSubKind()] {
    return fmt.Errorf("integration subkind %q not supported by this Teleport version", ig.GetSubKind())
}

func isSupportedIntegrationSubKind(sk types.IntegrationSubKind) bool {
    switch sk {
    case types.IntegrationSubKindAWSOIDC, types.IntegrationSubKindAWSRolesAnywhere:
        return true
    }
    return false
}

igMeta, err := getIntegrationMetadata(ig)
if err != nil {
    if strings.HasPrefix(err.Error(), "unknown integration subkind") {
        return trace.BadParameter("integration %q has unsupported subkind %q; upgrade Teleport or fix the resource", ig.GetName(), ig.GetSubKind())
    }
    return trace.Wrap(err)
}

When it happens

Trigger: Calling CreateIntegration, UpdateIntegration, or DeleteIntegration with an Integration whose spec SubKind is not one handled by the switch (e.g. a newly introduced subkind lacking a case, a typo'd subkind string, or a resource created by a newer Teleport version parsed by an older one).

Common situations: Running an older Teleport auth server against integration resources created by a newer version; hand-crafted YAML for integrations with an invalid spec.sub_kind; plugin development where a new IntegrationSubKind constant was defined in types but the audit-event metadata mapping in lib/auth/integration/integrationv1 was not updated.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• unable to serve request due to an app configuration error. C
• unable to serve the request due to an internal error. Contac
• tokens quota exceeded. Contact your Teleport administrator
• the inference provider returned an unexpected error. Contact
• session chunk already closed

AI-assisted analysis of gravitational/teleport@1283425b60 (2026-09-02). Data as JSON: /api/errors/c16150d370b8ac44. Report an issue: GitHub.