Troubleshooting

Common issues and solutions when using the Gately SDK.

Authentication Issues

Invalid Project ID

Problem: Authentication fails with “Invalid project ID” error.Solutions:

Verify your project ID in the Gately dashboard
Check that you’re using the correct environment (dev/staging/prod)
Ensure the project ID is a valid UUID format

// Check your project ID format
const projectId = 'your-project-id' // Should be UUID format
console.log('Project ID:', projectId)

// Verify initialization
const gately = new GatelyBrowserClient(projectId)
console.log('SDK initialized:', !!gately)

CORS Errors

Problem: Cross-origin request blocked errors in browser console.Solutions:

Add your domain to allowed origins in the Gately dashboard
Ensure you’re using HTTPS in production
Check if you’re testing from localhost vs 127.0.0.1

// Check current origin
console.log('Current origin:', window.location.origin)

// Verify in dashboard that this origin is whitelisted

Network Connectivity

Problem: Network errors or timeouts during authentication.Solutions:

Check internet connection
Verify firewall settings
Test API connectivity directly

// Test API connectivity
async function testConnectivity() {
  try {
    const response = await fetch('https://sdk.usegately.com/health')
    console.log('API Status:', response.status)
  } catch (error) {
    console.error('Connectivity issue:', error)
  }
}

Session Management Issues

User Not Persisting

Problem: User session doesn’t persist across page reloads.Solutions:

Check if cookies are enabled in browser
Verify localStorage is available
Ensure you’re not in incognito/private mode

// Debug session persistence
console.log('Cookies enabled:', navigator.cookieEnabled)
console.log('LocalStorage available:', typeof Storage !== 'undefined')
console.log('Current session:', gately.getSession())

// Check for incognito mode
if (window.webkitRequestFileSystem) {
  window.webkitRequestFileSystem(
    window.TEMPORARY, 1,
    () => console.log('Not in incognito'),
    () => console.log('In incognito mode')
  )
}

Token Expiration

Problem: User gets logged out unexpectedly.Solutions:

Enable auto-refresh in SDK options
Handle token refresh manually
Check token expiration times

// Enable auto-refresh
const gately = new GatelyBrowserClient('project-id', {
  autoRefresh: true
})

// Manual token refresh check
const session = gately.getSession()
if (session && session.expires_at < Date.now()) {
  console.log('Token expired, refreshing...')
  // SDK will handle refresh automatically
}

SSO Issues

Popup Blocked

Problem: OAuth popup is blocked by browser.Solutions:

Use redirect mode as fallback
Ensure popup is triggered by user action
Add popup blocker detection

async function loginWithGoogleSafe() {
  try {
    await gately.loginWithGoogle({ mode: 'popup' })
  } catch (error) {
    if (error.code === 'POPUP_BLOCKED') {
      console.log('Popup blocked, falling back to redirect')
      await gately.loginWithGoogle({ mode: 'redirect' })
    } else {
      throw error
    }
  }
}

OAuth Configuration

Problem: OAuth provider returns configuration errors.Solutions:

Verify OAuth app settings in provider dashboard
Check redirect URIs are correctly configured
Ensure client ID and secret are correct

// Debug OAuth configuration
try {
  await gately.loginWithGoogle()
} catch (error) {
  if (error.code === 'PROVIDER_NOT_CONFIGURED') {
    console.error('Google OAuth not configured in Gately dashboard')
  } else if (error.code === 'INVALID_REDIRECT_URL') {
    console.error('Redirect URL not whitelisted')
  }
}

Mobile SSO Issues

Mobile Popup Issues

Problem: OAuth popups don’t work well on mobile devices.Solutions:

Always use redirect mode on mobile
Detect mobile devices and adjust accordingly

function isMobile() {
  return /Android|webOS|iPhone|iPad|iPod|BlackBerry|IEMobile|Opera Mini/i.test(navigator.userAgent)
}

async function smartOAuthLogin() {
  const mode = isMobile() ? 'redirect' : 'popup'
  await gately.loginWithGoogle({ mode })
}

UI Control Issues

Elements Not Showing/Hiding

Element Not Found

Problem: UI control methods don’t work because element doesn’t exist.Solutions:

Ensure element exists in DOM before setting up controls
Use proper element IDs
Check timing of control setup

// Debug element existence
function setupUIControls() {
  const element = document.getElementById('dashboard')
  if (!element) {
    console.error('Dashboard element not found')
    return
  }
  
  gately.showElementOnAuth('dashboard', { hideIfLoggedOut: true })
}

// Wait for DOM to be ready
document.addEventListener('DOMContentLoaded', setupUIControls)

Controls Not Working

Problem: UI controls are set up but elements don’t show/hide correctly.Solutions:

Check authentication state
Verify control options
Debug CSS conflicts

// Debug UI controls
function debugUIControls() {
  console.log('Is authenticated:', gately.isAuthenticated())
  console.log('Current user:', gately.getUser())
  
  const element = document.getElementById('dashboard')
  console.log('Element display:', element?.style.display)
  console.log('Element classes:', element?.className)
}

React Integration Issues

Hook Not Working

Hook Returns Null

Problem: useGately hook returns null values.Solutions:

Check project ID is correct
Ensure hook is used inside component
Verify React version compatibility

function DebugComponent() {
  const hookResult = useGately('your-project-id')
  
  console.log('Hook result:', hookResult)
  console.log('User:', hookResult.user)
  console.log('Loading:', hookResult.loading)
  console.log('Error:', hookResult.error)
  
  return <div>Check console for debug info</div>
}

Infinite Re-renders

Problem: Component re-renders infinitely when using the hook.Solutions:

Avoid creating new objects in render
Use proper dependency arrays
Memoize callback functions

function Component() {
  const { user, login } = useGately('project-id')
  
  // Good: Memoized callback
  const handleLogin = useCallback(async (email, password) => {
    await login(email, password)
  }, [login])
  
  // Bad: New function on every render
  // const handleLogin = async (email, password) => {
  //   await login(email, password)
  // }
  
  return <button onClick={handleLogin}>Login</button>
}

Performance Issues

Slow Authentication

Multiple SDK Instances

Problem: Creating multiple SDK instances causes performance issues.Solutions:

Create single SDK instance
Use context or global state
Implement proper singleton pattern

// Good: Single instance
const gately = new GatelyBrowserClient('project-id')

// Bad: Multiple instances
function Component() {
  const gately = new GatelyBrowserClient('project-id') // Don't do this
}

Unnecessary API Calls

Problem: Too many API calls slowing down the application.Solutions:

Cache user data appropriately
Use loading states to prevent duplicate calls
Implement request deduplication

// Implement simple caching
let profileCache = null
let profileCacheTime = 0
const CACHE_TTL = 5 * 60 * 1000 // 5 minutes

async function getCachedProfile() {
  const now = Date.now()
  if (profileCache && (now - profileCacheTime) < CACHE_TTL) {
    return profileCache
  }
  
  profileCache = await gately.getUserProfile()
  profileCacheTime = now
  return profileCache
}

Development Environment Issues

Local Development

Localhost vs 127.0.0.1

Problem: Authentication works on localhost but not 127.0.0.1 or vice versa.Solutions:

Add both localhost and 127.0.0.1 to allowed origins
Use consistent URL format
Check browser cookie settings

// Check current host
console.log('Current host:', window.location.host)

// Ensure both are whitelisted in dashboard:
// - http://localhost:3000
// - http://127.0.0.1:3000

Hot Reload Issues

Problem: Authentication state lost during hot reload in development.Solutions:

This is expected behavior in development
Test in production build for accurate behavior
Use development-specific handling if needed

// Development-specific handling
if (process.env.NODE_ENV === 'development') {
  // Handle hot reload state loss
  console.log('Development mode: state may reset on hot reload')
}

Error Debugging

Enable Debug Logging

// Enable detailed logging
const gately = new GatelyBrowserClient('project-id', {
  debug: true
})

// Manual logging
gately.onAuthStateChange((user, session) => {
  console.log('Auth state change:', {
    user: user ? { id: user.id, email: user.email } : null,
    session: session ? { expires_at: session.expires_at } : null,
    timestamp: new Date().toISOString()
  })
})

Network Debugging

// Monitor network requests
const originalFetch = window.fetch
window.fetch = function(...args) {
  console.log('Fetch request:', args[0])
  return originalFetch.apply(this, args)
    .then(response => {
      console.log('Fetch response:', response.status, args[0])
      return response
    })
    .catch(error => {
      console.error('Fetch error:', error, args[0])
      throw error
    })
}

Getting Help

Before Contacting Support

Check the Console: Look for error messages in browser developer tools
Verify Configuration: Double-check project ID and domain settings
Test in Incognito: Rule out browser extension conflicts
Try Different Browser: Check if issue is browser-specific
Check Network: Verify internet connection and firewall settings

Information to Include

When contacting support, include:

Project ID (without sensitive data)
Browser and version
Operating system
Error messages from console
Steps to reproduce the issue
Expected vs actual behavior

Debug Information Script

// Run this script to gather debug information
function gatherDebugInfo() {
  const info = {
    userAgent: navigator.userAgent,
    url: window.location.href,
    cookiesEnabled: navigator.cookieEnabled,
    localStorageAvailable: typeof Storage !== 'undefined',
    isAuthenticated: gately.isAuthenticated(),
    user: gately.getUser() ? 'Present' : 'Null',
    session: gately.getSession() ? 'Present' : 'Null',
    timestamp: new Date().toISOString()
  }
  
  console.log('Debug Info:', JSON.stringify(info, null, 2))
  return info
}

// Call when experiencing issues
gatherDebugInfo()

Next Steps

Best Practices

Tips and recommendations

Examples

Working code examples

API Reference

Complete API documentation

Get Started

Framer Integration

Features

Knowledge Base

React Integration

Webflow Integration

No-Code Tools

Developers

API Documentation

Authentication Issues

Session Management Issues

SSO Issues

Mobile SSO Issues

UI Control Issues

Elements Not Showing/Hiding

React Integration Issues

Hook Not Working

Performance Issues

Slow Authentication

Development Environment Issues

Local Development

Error Debugging

Enable Debug Logging

Network Debugging

Getting Help

Before Contacting Support

Information to Include

Debug Information Script

Next Steps

Best Practices

Examples

API Reference

Get Started

Framer Integration

Features

Knowledge Base

React Integration

Webflow Integration

No-Code Tools

Developers

API Documentation

​Authentication Issues

​Login/Signup Not Working

​Session Management Issues

​SSO Issues

​OAuth Popup Problems

​Mobile SSO Issues

​UI Control Issues

​Elements Not Showing/Hiding

​React Integration Issues

​Hook Not Working

​Performance Issues

​Slow Authentication

​Development Environment Issues

​Local Development

​Error Debugging

​Enable Debug Logging

​Network Debugging

​Getting Help

​Before Contacting Support

​Information to Include

​Debug Information Script

​Next Steps

Best Practices

Examples

API Reference

Authentication Issues

Login/Signup Not Working

Session Management Issues

SSO Issues

OAuth Popup Problems

Mobile SSO Issues

UI Control Issues

Elements Not Showing/Hiding

React Integration Issues

Hook Not Working

Performance Issues

Slow Authentication

Development Environment Issues

Local Development

Error Debugging

Enable Debug Logging

Network Debugging

Getting Help

Before Contacting Support

Information to Include

Debug Information Script

Next Steps