How to fix manual_linking_disabled: Manual identity linking is disabled in Supabase

SupabaseBEGINNERMEDIUMUpdated Dec 18, 2025· 172 views

This error occurs when attempting to link an OAuth identity to an existing user via linkIdentity() while the manual linking feature is disabled in your Supabase project settings. Manual linking must be explicitly enabled for security reasons.

Quick fix

Fixes manual_linking_disabled

GOTRUE_SECURITY_MANUAL_LINKING_ENABLED=true
  1. Enable manual linking in Supabase dashboard (hosted projects)
  2. Set environment variable for self-hosted Supabase
  3. Update local Supabase services for development
  4. Verify user is authenticated before calling linkIdentity()
supabase — error
GOTRUE_SECURITY_MANUAL_LINKING_ENABLED=true
manual_linking_disabled: Manual identity linking is disabled

What this error means

This error indicates that you're trying to use Supabase's `linkIdentity()` method to manually link an OAuth provider identity (like Google, GitHub, or Apple) to an existing authenticated user, but the manual identity linking feature is not enabled in your project configuration. Manual identity linking is a security-sensitive feature that allows developers to programmatically connect multiple OAuth identities to a single user account. For example, a user who initially signed up with email/password could later link their Google or GitHub account to the same profile. Because this feature can be misused if not properly secured, Supabase disables it by default and requires explicit opt-in through project settings. When you call `linkIdentity()` without enabling this feature, Supabase's GoTrue authentication service returns a 404 error with the message "Manual linking is disabled" to prevent unauthorized identity manipulation.

Typical symptoms

  • Calling supabase.auth.linkIdentity() returns a 404 error
  • Error response contains "manual_linking_disabled" code
  • Identity linking fails even when user is properly authenticated
  • OAuth flow completes successfully but identity is not attached to user
  • Local development with GOTRUE_SECURITY_MANUAL_LINKING_ENABLED="true" still fails on older GoTrue versions

Common causes

  1. Manual identity linking is disabled by default in Supabase projects for security
  2. Project authentication settings have not been updated to enable manual linking
  3. Self-hosted Supabase instance missing GOTRUE_SECURITY_MANUAL_LINKING_ENABLED environment variable
  4. Local development environment running an outdated version of GoTrue service
  5. Attempting to use linkIdentity() without checking project configuration first

How to fix "manual_linking_disabled: Manual identity linking is disabled"

1Enable manual linking in Supabase dashboard (hosted projects)

For hosted Supabase projects, enable manual linking through the dashboard:

1. Navigate to your project in the Supabase Dashboard
2. Go to Authentication → Settings
3. Scroll to the Security and Protection section
4. Find the Enable Manual Linking option
5. Toggle it ON
6. Save your changes

The feature should be immediately available after enabling.

2Set environment variable for self-hosted Supabase

If you're self-hosting Supabase, add the environment variable to your GoTrue configuration:

bash
GOTRUE_SECURITY_MANUAL_LINKING_ENABLED=true

Add this to your .env file or Docker Compose configuration:

yaml
services:
  auth:
    environment:
      GOTRUE_SECURITY_MANUAL_LINKING_ENABLED: true

Restart the GoTrue service after making this change.

3Update local Supabase services for development

If you're running Supabase locally and the environment variable doesn't work, your GoTrue version may be outdated:

bash
# Update Supabase CLI
npm install -g supabase@latest

# Stop local services
supabase stop

# Pull latest service images
supabase db reset

# Start with updated services
supabase start

Verify GoTrue is updated by checking the logs:

bash
supabase status
4Verify user is authenticated before calling linkIdentity()

Ensure the user is signed in before attempting to link an identity:

typescript
const { data: { user } } = await supabase.auth.getUser();

if (!user) {
  throw new Error('User must be authenticated to link identities');
}

// Now safe to call linkIdentity
const { data, error } = await supabase.auth.linkIdentity({
  provider: 'google',
});

if (error) {
  console.error('Failed to link identity:', error.message);
}
5Implement proper error handling for linking failures

Handle various error scenarios when linking identities:

typescript
async function linkGoogleAccount() {
  try {
    const { data, error } = await supabase.auth.linkIdentity({
      provider: 'google',
    });

    if (error) {
      if (error.message.includes('manual_linking_disabled')) {
        console.error('Manual linking is not enabled in project settings');
        // Show user-friendly message
      } else if (error.message.includes('already linked')) {
        console.error('This identity is already linked to another account');
      } else {
        console.error('Failed to link identity:', error);
      }
      return;
    }

    // For web: user will be redirected to OAuth provider
    // For mobile: handle the response
    console.log('Identity linking initiated:', data);
  } catch (err) {
    console.error('Unexpected error during identity linking:', err);
  }
}

Advanced notes

Understanding Identity Linking Modes

Supabase offers two identity linking approaches:

1. Automatic Linking: Enabled by default. Supabase automatically links identities with matching email addresses to the same user account. This improves UX when users sign in with different OAuth providers.

2. Manual Linking: Requires explicit configuration. Gives developers programmatic control over linking identities via linkIdentity(), useful for cases like:
 - Linking anonymous users to permanent accounts
 - Adding OAuth providers to existing email/password accounts
 - Building custom account management flows

Mobile Native OAuth Flows

For mobile apps using native OAuth (Google Sign-In SDK, Sign in with Apple), you can link identities using ID tokens:

typescript
const { data, error } = await supabase.auth.linkIdentity({
  provider: 'google',
  options: {
    idToken: googleIdToken, // From native SDK
  },
});

Security Considerations

Manual linking is disabled by default because:
- Malicious code could link unauthorized identities to user accounts
- Improperly validated OAuth flows could enable account takeover
- Identity linking should be protected by proper user intent verification

Always verify user intent before linking identities and implement rate limiting for linking operations.

Unlinking Identities

Users must have at least 2 linked identities to unlink one:

typescript
// Get all identities
const { data: identities } = await supabase.auth.getUserIdentities();

if (identities && identities.length > 1) {
  // Safe to unlink
  await supabase.auth.unlinkIdentity({
    identity_id: identityToRemove.id,
  });
}

Checking Configuration Status

There's no direct API to check if manual linking is enabled. The best approach is to catch the error and guide users to enable it in settings.

Frequently asked questions

What does "manual_linking_disabled" mean?
This error indicates that you're trying to use Supabase's linkIdentity() method to manually link an OAuth provider identity (like Google, GitHub, or Apple) to an existing authenticated user, but the manual identity linking feature is not enabled in your project configuration. Manual identity linking is a security-sensitive feature that allows developers to programmatically connect multiple OAuth identities to a single user account. For example, a user who initially signed up with email/password could later link their Google or GitHub account to the same profile.
How do I fix "manual_linking_disabled"?
This error occurs when attempting to link an OAuth identity to an existing user via linkIdentity() while the manual linking feature is disabled in your Supabase project settings. Manual linking must be explicitly enabled for security reasons.
What causes "manual_linking_disabled"?
Manual identity linking is disabled by default in Supabase projects for security Project authentication settings have not been updated to enable manual linking Self-hosted Supabase instance missing GOTRUE_SECURITY_MANUAL_LINKING_ENABLED environment variable
Is the "manual_linking_disabled" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading