Home
JS SDK (Browser)
JS SDK (Server)
FAQ
Home
JS SDK (Browser)
JS SDK (Server)
FAQ

Troubleshooting

This guide helps you diagnose and resolve common issues when working with the Asterisms JS SDK.

Common Issues

Authentication Issues

Invalid Token Error

Problem: Getting InvalidTokenError or authentication failures Solutions:

  1. Check if token has expired
  2. Verify provider configuration
  3. Clear stored tokens and re-authenticate
// Clear tokens and re-authenticate
localStorage.removeItem('asterisms-token');
await sdk.auth.logout();
await sdk.auth.login({ provider: 'srp6', credentials });

Provider Not Found

Problem: Error "Authentication provider not found" Solution: Ensure provider is registered before use

import { SRP6AuthProvider } from '@asterisms/auth-provider-srp6';

// Register provider first
sdk.auth.registerProvider(
  'srp6',
  new SRP6AuthProvider({
    serviceUrl: 'https://auth.yourapp.com'
  })
);

// Then use it
await sdk.auth.login({ provider: 'srp6', credentials });

Network Issues

CORS Errors

Problem: Cross-origin request blocked Solutions:

  1. Configure proper CORS headers on your backend
  2. Use proxy in development
  3. Check domain configuration

Request Timeout

Problem: Network requests timing out Solution: Increase timeout configuration

const sdk = createAsterismsSDK({
  bundleId: 'your-app',
  rootDomain: 'yourapp.com',
  navigationAdapter: yourAdapter,
  timeout: 60000, // Increase to 60 seconds
  retryAttempts: 5
});

File Upload Issues

File Too Large

Problem: Upload fails with file size error Solution: Check and adjust file size limits

const sdk = createAsterismsSDK({
  // ... other config
  resources: {
    storage: {
      maxFileSize: 200 * 1024 * 1024 // Increase to 200MB
    }
  }
});

Upload Progress Not Working

Problem: Progress events not firing Solution: Use uploadWithProgress method

const upload = sdk.storage.uploadWithProgress(file);
upload.onProgress((progress) => {
  console.log(`Progress: ${progress.percentage}%`);
});
const result = await upload.promise;

TypeScript Issues

Type Errors

Problem: TypeScript compilation errors Solutions:

  1. Update TypeScript version
  2. Add proper type imports
  3. Configure tsconfig properly
{
  "compilerOptions": {
    "types": ["@asterisms/sdk"],
    "moduleResolution": "node",
    "esModuleInterop": true
  }
}

Debugging Techniques

Enable Debug Logging

const sdk = createAsterismsSDK({
  bundleId: 'your-app',
  rootDomain: 'yourapp.com',
  navigationAdapter: yourAdapter,
  logLevel: 'debug', // Enable debug logging
  enableConsoleLogging: true
});

Monitor Network Requests

// Add request interceptor for debugging
sdk.addRequestInterceptor((config) => {
  console.log('Request:', config);
  return config;
});

sdk.addResponseInterceptor(
  (response) => {
    console.log('Response:', response);
    return response;
  },
  (error) => {
    console.error('Request Error:', error);
    throw error;
  }
);

Check SDK Status

// Verify SDK initialization
console.log('SDK Ready:', sdk.isReady());
console.log('Auth Status:', sdk.auth.isAuthenticated());
console.log('Current User:', sdk.auth.getCurrentUser());

Performance Issues

Slow API Responses

Problem: API calls taking too long Solutions:

  1. Enable caching
  2. Use pagination for large datasets
  3. Optimize network configuration
const sdk = createAsterismsSDK({
  // ... other config
  resources: {
    drive: {
      cacheEnabled: true,
      cacheTTL: 300000 // 5 minutes
    }
  }
});

Memory Leaks

Problem: Application memory usage growing Solutions:

  1. Properly unsubscribe from events
  2. Clear unused data
  3. Monitor event listeners
// Proper event cleanup
useEffect(() => {
  const unsubscribe = sdk.auth.onAuthStateChanged(callback);
  return unsubscribe; // Important: cleanup on unmount
}, []);

Error Messages Reference

Common Error Codes

Error Code Description Solution
AUTH_001 Invalid credentials Check username/password
AUTH_002 Token expired Refresh token or re-authenticate
NET_001 Network timeout Check connection, increase timeout
NET_002 CORS error Configure server CORS headers
FILE_001 File too large Reduce file size or increase limit
FILE_002 Invalid file type Check allowed file types

Error Handling Best Practices

try {
  const result = await sdk.storage.upload(file);
} catch (error) {
  if (error instanceof AsterismsBackendError) {
    switch (error.status) {
      case 401:
        // Handle authentication error
        await sdk.auth.refreshToken();
        break;
      case 413:
        // Handle file too large
        alert('File is too large. Please choose a smaller file.');
        break;
      case 500:
        // Handle server error
        console.error('Server error:', error.message);
        break;
      default:
        console.error('Unexpected error:', error);
    }
  } else if (error instanceof AsterismsError) {
    // Handle SDK-specific errors
    console.error('SDK Error:', error.message);
  } else {
    // Handle unexpected errors
    console.error('Unexpected error:', error);
  }
}

Browser Compatibility

Supported Browsers

  • Chrome 80+
  • Firefox 75+
  • Safari 13+
  • Edge 80+

Feature Detection

// Check for required features
if (!('fetch' in window)) {
  console.error('Fetch API not supported');
}

if (!('Promise' in window)) {
  console.error('Promises not supported');
}

if (!('localStorage' in window)) {
  console.warn('localStorage not available, using memory storage');
}

Development Tools

Browser DevTools

  1. Open DevTools (F12)
  2. Check Console for errors
  3. Monitor Network tab for failed requests
  4. Use Application tab to inspect stored data

SDK Debug Panel

Enable development tools for additional debugging:

const sdk = createAsterismsSDK({
  // ... other config
  development: {
    enableDevTools: true,
    debugEvents: true
  }
});

Getting Help

Before Asking for Help

  1. Check this troubleshooting guide
  2. Search existing GitHub issues
  3. Review your code for common mistakes
  4. Test with minimal reproduction case

Creating Bug Reports

Include the following information:

  • SDK version
  • Browser/Node.js version
  • Minimal code reproduction
  • Error messages and stack traces
  • Expected vs actual behavior

Community Resources

ON THIS PAGE