> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stringboot.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Resolve common issues with the Web SDK

Common pitfalls and solutions when integrating the Stringboot Web SDK.

## Common Issues

### Strings return empty or "undefined"

**Symptoms:** `StringBoot.get()` returns `undefined` or empty strings.

**Solutions:**

* Ensure you have awaited `StringBoot.initialize()` before calling `.get()`.
* Check browser console for initialization errors (enable `debug: true`).
* Verify your API token is correct.
* Check the network tab in DevTools; look for 401 or 403 errors on `api.stringboot.com` requests.

### TypeScript errors: "Module not found"

**Symptoms:** `Cannot find module '@stringboot/web-sdk'`

**Solutions:**

* Ensure you have installed the package: `npm install @stringboot/web-sdk`.
* Install node type definitions: `npm install --save-dev @types/node`.
* Update your `tsconfig.json`:
  ```json theme={null}
  {
    "compilerOptions": {
      "moduleResolution": "bundler",
      "allowSyntheticDefaultImports": true
    }
  }
  ```

### "Cannot use import statement outside a module"

**Symptoms:** Crash on startup or build time error.

**Solutions:**

* If using basic HTML/JS, ensure your script tag has `type="module"`.
* If using Node.js/SSR, add `"type": "module"` to your `package.json`.
* Or use the CommonJS import syntax: `const StringBoot = require('@stringboot/web-sdk').default;`.

### Strings don't update when changing language

**Symptoms:** Calling `changeLanguage` updates the internal state, but the UI remains in the old language.

**Solutions:**

* **Vanilla JS**: Ensure you are using `StringBoot.watch()` or manually updating DOM elements after the promise resolves.
* **React**: Ensure you are using the `useString()` hook, which subscribes to updates.
* **Vue**: Ensure you are using reactive refs or the composition API hooks.

### Large bundle size warning

**Symptoms:** Build tools warn about the SDK size.

**Solutions:**

* The SDK is lightweight (\~6.6kB gzipped).
* Ensure you are using named imports to allow tree-shaking:
  ```javascript theme={null}
  // ✅ Good
  import { useString } from '@stringboot/web-sdk/react';

  // ❌ Bad (imports everything)
  import * as StringBootReact from '@stringboot/web-sdk/react';
  ```

### Offline mode not working

**Symptoms:** App fails to load strings when network is disabled.

**Solutions:**

* Strings are cache-first. They must be loaded at least once with a network connection to populate the cache.
* Clear your browser data to reset the test state: DevTools → Application → Clear storage.
* Verify that `IndexedDB` contains a database starting with `stringboot_`.

## Need more help?

* [Contact Support](mailto:support@stringboot.com)
* [Report specific issues on GitHub](https://github.com/stringboot/web-sdk/issues)