Skip to main content

JavaScript SDK Troubleshooting

Solutions for JavaScript/TypeScript-specific issues.

Installation Issues​

Package Not Found​

# Verify package name
npm install @ops-ai/feature-flags-toggly

# Or with yarn
yarn add @ops-ai/feature-flags-toggly

TypeScript Errors​

// If types are not found, ensure you have TypeScript installed
npm install --save-dev typescript @types/node

// Or add type reference
/// <reference types="@ops-ai/feature-flags-toggly" />

Initialization Problems​

SDK Not Initializing​

// ❌ Common mistake - not awaiting init
const toggly = new TogglyClient({ appKey: '...', environment: 'production' });
const result = toggly.isEnabled('feature'); // Returns undefined!

// ✅ Correct - wait for initialization
const toggly = new TogglyClient({ appKey: '...', environment: 'production' });
await toggly.init();
const result = toggly.isEnabled('feature'); // Works!

Initialization Timeout​

// Increase timeout if needed
const toggly = new TogglyClient({
  appKey: 'your-key',
  environment: 'production',
  timeout: 10000, // 10 seconds instead of default 5s
});

Browser-Specific Issues​

CORS Errors​

See Network & CORS Guide for detailed solutions.

Quick fix:

// Ensure you're using client endpoint
const toggly = new TogglyClient({
  appKey: 'your-key',
  environment: 'production',
  baseURL: 'https://definitions.toggly.io', // CORS-enabled for browsers
});

LocalStorage Not Available​

// For environments without localStorage (SSR, Workers)
const toggly = new TogglyClient({
  appKey: 'your-key',
  environment: 'production',
  storage: null, // Disable storage
  // Or provide custom storage
  storage: customStorageAdapter,
});

API Key Issues​

See Authentication Guide for general authentication issues.

Invalid API Key Format​

// ❌ Wrong - using environment variable name
const toggly = new TogglyClient({
  appKey: 'TOGGLY_APP_KEY', // This is the variable NAME!
  environment: 'production'
});

// ✅ Correct - using the actual key value
const toggly = new TogglyClient({
  appKey: process.env.TOGGLY_APP_KEY, // Value from env var
  environment: 'production'
});

Network Configuration​

Proxy Setup​

// For Node.js with proxy
import { HttpsProxyAgent } from 'https-proxy-agent';

const toggly = new TogglyClient({
  appKey: 'your-key',
  environment: 'production',
  httpAgent: new HttpsProxyAgent('http://proxy.company.com:8080'),
});

Custom Headers​

const toggly = new TogglyClient({
  appKey: 'your-key',
  environment: 'production',
  headers: {
    'X-Custom-Header': 'value',
  },
});

Performance Optimization​

Bundle Size​

// Use dynamic imports to reduce initial bundle
const loadToggly = async () => {
  const { TogglyClient } = await import('@ops-ai/feature-flags-toggly');
  return new TogglyClient({...});
};

Memory Leaks​

// ❌ Bad - creating new instance repeatedly
setInterval(() => {
  const toggly = new TogglyClient({...}); // Memory leak!
}, 1000);

// ✅ Good - reuse single instance
const toggly = new TogglyClient({...});
setInterval(() => {
  toggly.refresh(); // Just refresh data
}, 60000);

Evaluation Issues​

Undefined Results​

// Check if SDK is initialized
if (!toggly.isInitialized) {
  console.warn('Toggly not initialized yet');
  await toggly.init();
}

// Now evaluate
const result = toggly.isEnabled('feature');

Stale Values​

// Force refresh to get latest definitions
await toggly.refresh();

// Or set auto-refresh interval
const toggly = new TogglyClient({
  appKey: 'your-key',
  environment: 'production',
  refreshInterval: 60000, // Refresh every minute
});

Error Handling​

Graceful Degradation​

const toggly = new TogglyClient({
  appKey: 'your-key',
  environment: 'production',
  
  // Provide defaults for all flags
  defaults: {
    'new-feature': false,
    'beta-feature': false,
  },
  
  // Handle errors gracefully
  onError: (message, error) => {
    console.error('Toggly error:', message, error);
    // Log to monitoring service
  },
});

// SDK preserves last-known-good flags when available, then falls back to defaults
const isEnabled = toggly.isEnabled('new-feature'); // Returns false if error

Promise Rejections​

// Handle initialization errors
try {
  await toggly.init();
} catch (error) {
  console.error('Failed to initialize Toggly:', error);
  // Use default behavior
}

Common Pitfalls​

1. Not Awaiting Async Operations​

// ❌ Wrong
toggly.init();
const result = toggly.isEnabled('feature'); // May return undefined

// ✅ Correct
await toggly.init();
const result = toggly.isEnabled('feature');

2. Creating Multiple Instances​

// ❌ Bad - waste of memory and network
function MyComponent() {
  const toggly = new TogglyClient({...}); // New instance every render!
}

// ✅ Good - singleton pattern
// toggly.ts
export const toggly = new TogglyClient({...});

// MyComponent.tsx
import { toggly } from './toggly';

3. Not Handling Errors​

// ❌ Bad - no error handling
await toggly.init(); // Throws if API is down

// ✅ Good - graceful fallback
try {
  await toggly.init();
} catch (error) {
  console.warn('Using default flag values');
}

Debugging​

Enable Debug Mode​

const toggly = new TogglyClient({
  appKey: 'your-key',
  environment: 'production',
  debug: true, // Enable verbose logging
});

Check SDK State​

// Verify SDK state
console.log('Initialized:', toggly.isInitialized);
console.log('All flags:', toggly.getAllFlags());
console.log('Definitions:', toggly.getDefinitions());

Getting More Help​