Skip to main content

​
Common Issues

This guide covers the most common issues you might encounter and how to resolve them.

​
Initialization Issues

Problem: Strings display as ??welcome_message?? instead of actual contentPossible Causes:
  • SDK not initialized
  • String key doesn’t exist in backend
  • Network sync hasn’t completed
  • Invalid API token
Solutions:
  • Web
  • Android
  • iOS
// 1. Check if SDK is initialized
console.log('SDK initialized:', StringBoot.isReady);

// 2. Trigger manual sync
try {
  await StringBoot.syncNow();
} catch (error) {
  console.error('Sync failed:', error);
}

// 3. Check if key exists
const text = await StringBoot.get('welcome_message');
if (text.startsWith('??')) {
  console.error('String not found:', text);
}

// 4. Verify API token in initialization
await StringBoot.initialize({
  apiToken: 'verify-this-is-correct',
  baseUrl: 'https://api.stringboot.com'
});
Problem: SDK fails to initialize or gets stuck in loading stateCommon Causes:
  • Invalid API token
  • Wrong baseURL
  • Network firewall blocking requests
  • Missing internet permission (mobile)
Solutions:Web:
try {
  await StringBoot.initialize({
    apiToken: 'check-this-token',
    baseUrl: 'https://api.stringboot.com', // Check URL is correct
    defaultLanguage: 'en',
    debug: true // Enable for more info
  });
} catch (error) {
  console.error('Init error:', error);
  // Check browser console for details
}
Android:
<!-- Verify AndroidManifest.xml -->
<uses-permission android:name="android.permission.INTERNET" />

<meta-data
    android:name="com.stringboot.api_url"
    android:value="https://api.stringboot.com" />
<meta-data
    android:name="com.stringboot.api_token"
    android:value="YOUR_VALID_TOKEN" />
iOS:
// Enable logging to see what's happening
StringbootLogger.isLoggingEnabled = true
StringbootLogger.logLevel = .debug

StringProvider.shared.initialize(
    cacheSize: 1000,
    apiToken: "verify-this-token",
    baseURL: "https://api.stringboot.com",
    autoSync: true
)
Problem: App takes too long to load strings on first launchCause: Cache is cold, requires network fetchSolution: Preload strings synchronously
  • Web
  • Android
  • iOS
// Preload during initialization
await StringBoot.initialize({ /* config */ });

// Preload top strings
await StringBoot.syncNow();

​
Language Switching Issues

Problem: UI still shows old language after calling changeLanguage()Cause: UI not reacting to language changesSolutions:
  • Web (Vanilla JS)
  • Web (React)
  • Android
  • iOS
// Use watchers for automatic updates
StringBoot.watch('welcome_message', (value) => {
  document.getElementById('welcome').textContent = value;
});

// Then language change updates automatically
await StringBoot.changeLanguage('es');
Problem: Language change function called repeatedlyCause: UI not disabled during language changeSolution:
  • Web
  • iOS
languageSelect.addEventListener('change', async (e) => {
  languageSelect.disabled = true; // Disable during change

  try {
    await StringBoot.changeLanguage(e.target.value);
  } finally {
    languageSelect.disabled = false; // Re-enable
  }
});
Problem: Brief flash of old language before new language appearsCause: Cache is cold for new languageSolution: Preload language before switching
// Android
lifecycleScope.launch {
    StringProvider.setLocale("es")
    StringProvider.preloadLanguage("es", maxStrings = 500) // Prevent flash
    binding.root.applyStringbootTags()
}

// iOS
await StringProvider.shared.changeLanguage(to: "es")
// SDK automatically preloads

​
Platform-Specific Issues

  • Web
  • Android
  • iOS

​
Module not found error

Problem: Cannot find module '@stringboot/web-sdk'Solution:
# Reinstall package
npm install @stringboot/web-sdk

# Clear cache if needed
rm -rf node_modules package-lock.json
npm install

​
React hooks not working

Problem: Hooks don’t update or crashSolution:
// Must initialize SDK before using hooks
function App() {
  const { initialized } = useStringBoot({
    apiToken: 'token',
    baseUrl: 'url'
  });

  if (!initialized) return <Loading />;

  // Now safe to use other hooks
  return <MainContent />;
}

​
CORS errors

Problem: Browser blocks requests to Stringboot APISolution:
  • Verify baseUrl is correct: https://api.stringboot.com
  • Check that you’re not using http:// instead of https://
  • Contact support if CORS errors persist

​
IndexedDB errors

Problem: “Failed to open IndexedDB”Solution:
  • Check if private browsing is enabled (not supported)
  • Verify browser version meets minimum requirements
  • Clear browser data and try again

​
Network and Connectivity

Problem: “Network error” or “Request failed”Checklist:
  • Device has internet connection
  • baseURL is correct: https://api.stringboot.com
  • API token is valid (check dashboard)
  • No firewall blocking requests
  • Not in airplane mode
Test Connection:
# Test from command line
curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://api.stringboot.com/strings/meta
Problem: Sync takes >30 secondsPossible Causes:
  • Slow network connection
  • Large number of strings
  • Server issues
Solutions:
  • Use delta sync (enabled by default)
  • Preload during app initialization
  • Sync in background, don’t wait for completion
  • Check server status
Problem: App using too much dataCheck:
// Verify you're not force-refreshing too often
await StringBoot.syncNow(); // ✓ Good - uses ETag
await StringBoot.forceRefresh(); // ✗ Bad if done frequently
Best Practice:
  • Let SDK handle automatic sync
  • Only force-refresh when user explicitly requests
  • Use delta sync (default)

​
Debugging Tips

​
Enable Debug Logging

await StringBoot.initialize({
  apiToken: 'token',
  debug: true  // Logs all operations
});

​
Check Cache Stats

const stats = await StringBoot.getCacheStats();
console.log('Cache stats:', stats);
// {
//   memory: { size: 42, maxSize: 1000 },
//   db: { totalStrings: 150, deletedStrings: 3 }
// }

​
Test Offline Behavior

  1. Enable airplane mode
  2. Force quit app
  3. Relaunch app
  4. Verify: App should load all previously synced strings from cache

​
Inspect Network Requests

Web (Chrome DevTools):
  1. Open DevTools → Network tab
  2. Filter by “stringboot” or API domain
  3. Check request/response details
Android (Logcat): 
adb logcat | grep "OkHttp\|Stringboot"
iOS (Console App):
  1. Connect device
  2. Open Console app on Mac
  3. Filter by “Stringboot” or “URLSession”

​
Still Having Issues?

Check GitHub Issues

See if others have encountered similar issues

Review Docs

Re-read platform-specific documentation

Best Practices

Ensure you’re following recommended patterns

​
When Reporting Issues

Include the following information:
Platform and version (Web/Android/iOS)
SDK version
Error messages and stack traces
Steps to reproduce
Expected vs actual behavior
Debug logs if available
Network conditions when issue occurred

​
Next Steps

Error Handling

Proper error handling patterns

Best Practices

Production-ready tips

Caching

Understanding the cache system