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

# Troubleshooting

> Common issues and solutions for the AI Chat Extension SDK

## Overview

This guide covers common issues you may encounter when integrating the AI Chat Extension SDK and how to resolve them.

## Installation issues

### Package not found

**Symptom**: `npm install` or `pnpm add` fails with "package not found"

**Cause**: npm registry not configured or authentication token missing

**Solution**:

<Steps>
  <Step title="Add registry to .npmrc">
    ```bash .npmrc theme={null}
    @sleek:registry=https://npm.cloudsmith.io/sleek/sleek/
    //npm.cloudsmith.io/sleek/sleek/:_authToken={YOUR_TOKEN_HERE}
    ```
  </Step>

  <Step title="Replace token placeholder">
    Replace `{YOUR_TOKEN_HERE}` with your actual authentication token
  </Step>

  <Step title="Retry installation">
    ```bash theme={null}
    pnpm add @sleek/ai-chat-extension-sdk
    ```
  </Step>
</Steps>

<Note>
  Contact [support@onsleek.com](mailto:support@onsleek.com) if you need an authentication token.
</Note>

### Build errors after installation

**Symptom**: TypeScript or build errors after installing the SDK

**Cause**: Missing dependencies or TypeScript version mismatch

**Solution**:

```bash theme={null}
# Ensure peer dependencies are installed
pnpm install

# Check TypeScript version (should be 5.0+)
pnpm list typescript

# Update TypeScript if needed
pnpm add -D typescript@latest
```

## Manifest configuration issues

### SDK not initializing

**Symptom**: SDK initialization fails with manifest validation error

**Cause**: Missing required manifest permissions

**Solution**:

Verify your `manifest.json` includes:

```json manifest.json theme={null}
{
  "manifest_version": 3,
  "permissions": ["tabs", "scripting"],
  "host_permissions": ["<all_urls>"]
}
```

<Tip>
  Manifest validation is skipped by default. Set `skipManifestValidation: false` during development to catch manifest issues early.
</Tip>

### Content script not injecting

**Symptom**: Chat controller doesn't load, no badge or panel appears

**Cause**: Content script file not copied to extension directory

**Solution**:

<Steps>
  <Step title="Verify file is copied">
    ```bash theme={null}
    # Check that the file exists in your dist directory
    ls -la dist/chat-controller.js
    ```
  </Step>

  <Step title="Add copy step to build script">
    ```json package.json theme={null}
    {
      "scripts": {
        "build": "your-build-command && pnpm copy-sdk-files",
        "copy-sdk-files": "cp node_modules/@sleek/ai-chat-extension-sdk/dist/chat-controller.js dist/"
      }
    }
    ```
  </Step>

  <Step title="Rebuild extension">
    ```bash theme={null}
    pnpm build
    ```
  </Step>
</Steps>

## UI issues

### Chat badge not appearing

**Symptom**: No chat badge shows up after searching

**Causes**:

1. Query not classified as "shopping"
2. Badge feature not enabled
3. Branding configuration missing
4. Page is in denylist

**Solutions**:

<Accordion title="1. Test with explicit shopping query">
  Try clear shopping queries:

  * "best headphones"
  * "Nike running shoes"
  * "iPhone 15 deals"

  Enable debug mode to see classification results:

  ```typescript theme={null}
  enableDebug: true,
  ```
</Accordion>

<Accordion title="2. Verify feature is enabled">
  ```typescript theme={null}
  featureControls: {
    enableChatBadge: true,  // Must be true
  }
  ```
</Accordion>

<Accordion title="3. Check badge configuration">
  ```typescript theme={null}
  badgeConfig: {
    brand: {
      logoUrl: 'https://your-extension.com/badge-logo.png',
    },
  }
  ```
</Accordion>

<Accordion title="4. Verify platform is enabled">
  Check that the platform is enabled in your configuration:

  ```typescript theme={null}
  platformControls: {
    enableGoogle: true,   // For Google Search
    enableChatGPT: false, // For ChatGPT
  }
  ```
</Accordion>

### Chat panel not opening

**Symptom**: Clicking badge doesn't open chat panel

**Causes**:

1. Panel feature not enabled
2. Chat config missing or invalid
3. Content script not loaded

**Solutions**:

<Accordion title="1. Verify feature is enabled">
  ```typescript theme={null}
  featureControls: {
    enableChatPanel: true,  // Must be true
  }
  ```
</Accordion>

<Accordion title="2. Check content script is loaded">
  ```bash theme={null}
  ls -la dist/chat-controller.js
  ```
</Accordion>

<Accordion title="3. Check browser console for errors">
  Open DevTools Console and look for:

  * JavaScript errors
  * Network errors
  * CSP (Content Security Policy) errors
</Accordion>

### Panel appears blank

**Symptom**: Chat panel opens but shows blank white screen

**Causes**:

1. API key invalid
2. Network connectivity issues
3. JavaScript errors in content script

**Solutions**:

<Steps>
  <Step title="Check browser console">
    Look for JavaScript errors in DevTools Console
  </Step>

  <Step title="Verify API key">
    ```typescript theme={null}
    // Verify the API key passed as the first parameter is correct
    await initializeAiChatExtensionSdk('your-api-key', { ... });
    ```
  </Step>

  <Step title="Enable debug mode">
    ```typescript theme={null}
    enableDebug: true,
    ```
  </Step>
</Steps>

## Data provider issues

### Providers not being called

**Symptom**: Data providers never execute, no logs

**Causes**:

1. UI features disabled
2. No shopping queries detected
3. Panel not opened

**Solutions**:

<Accordion title="1. Verify UI features enabled">
  Data providers only execute when UI features are active:

  ```typescript theme={null}
  featureControls: {
    enableChatBadge: true,
    enableChatPanel: true,
  }
  ```
</Accordion>

<Accordion title="2. Test with shopping query">
  Search for "best laptops" on Google and open the chat panel
</Accordion>

<Accordion title="3. Add debug logging">
  ```typescript theme={null}
  dataProviders: {
    offerRedirectUrlProvider: async (url) => {
      console.log('Offer redirect url requested for:', url);
      const result = await fetchOfferRedirectUrl(url);
      console.log('Returning:', result);
      return result;
    },
  }
  ```
</Accordion>

### Provider errors breaking SDK

**Symptom**: SDK stops working after provider throws error

**Cause**: Exceptions thrown from data providers

**Solution**:

Always wrap providers in try-catch and return null/{}:

```typescript theme={null}
const offerRedirectUrlProvider = async (url) => {
  try {
    const response = await fetch(/* ... */);
    return response.offerRedirectUrl || null;
  } catch (error) {
    console.error('Offer redirect url error:', error);
    return null;  // Critical: return null, never throw
  }
};

const merchantCashbackProvider = async (urls) => {
  try {
    const response = await fetch(/* ... */);
    return response.cashback || {};
  } catch (error) {
    console.error('Cashback error:', error);
    return {};  // Critical: return {}, never throw
  }
};
```

### Slow performance

**Symptom**: Chat feels sluggish, UI freezes

**Cause**: Data providers taking too long to respond

**Solutions**:

<Accordion title="1. Add timeouts">
  ```typescript theme={null}
  const offerRedirectUrlProvider = async (url) => {
    const controller = new AbortController();
    const timeoutId = setTimeout(() => controller.abort(), 500);

    try {
      const response = await fetch(url, { signal: controller.signal });
      clearTimeout(timeoutId);
      return response.offerRedirectUrl || null;
    } catch (error) {
      clearTimeout(timeoutId);
      if (error.name === 'AbortError') {
        console.warn('Offer redirect url timeout');
      }
      return null;
    }
  };
  ```
</Accordion>

<Accordion title="2. Implement caching">
  ```typescript theme={null}
  const cache = new Map<string, string>();

  const offerRedirectUrlProvider = async (url) => {
    if (cache.has(url)) {
      return cache.get(url)!;
    }

    const result = await fetchOfferRedirectUrl(url);
    if (result) {
      cache.set(url, result);
    }
    return result;
  };
  ```
</Accordion>

<Accordion title="3. Measure performance">
  ```typescript theme={null}
  const offerRedirectUrlProvider = async (url) => {
    const start = performance.now();
    try {
      const result = await fetchOfferRedirectUrl(url);
      const duration = performance.now() - start;
      console.log(`Offer redirect url took ${duration.toFixed(0)}ms`);
      return result;
    } catch (error) {
      return null;
    }
  };
  ```

  Target \<500ms response times.
</Accordion>

## Event issues

### Events not firing

**Symptom**: Event listeners never called

**Cause**: Listener registered after events occurred

**Solution**:

Register listeners immediately after SDK initialization:

```typescript theme={null}
// Initialize SDK
await initializeAiChatExtensionSdk('your-api-key', {
  // ... config
});

// Register listener immediately
getAiChatExtensionSdk().registerEventListener((event, tabDetails) => {
  console.log('Event:', event.type);
});
```

<Note>
  You can also pass listeners during initialization as the third parameter.
</Note>

### Missing event data

**Symptom**: Event fires but `event.data` is undefined

**Cause**: Some events have no data payload (e.g., `CHAT_PANEL_CLOSED`)

**Solution**:

Check event type before accessing data:

```typescript theme={null}
getAiChatExtensionSdk().registerEventListener((event, tabDetails) => {
  switch (event.type) {
    case AiChatExtensionSdkEventType.QUERY_CLASSIFIED:
      console.log(event.data.query);  // Has data
      break;
    case AiChatExtensionSdkEventType.CHAT_PANEL_CLOSED:
      // No data payload for this event
      console.log('Panel closed (no data)');
      break;
  }
});
```

## Query classification issues

### All queries classified as "unknown"

**Symptom**: Shopping queries not detected, badge never shows

**Causes**:

1. Invalid API key
2. Network/firewall blocking API calls
3. Backend service unavailable

**Solutions**:

<Steps>
  <Step title="Verify API key">
    Check that your Pie AI API key is correct
  </Step>

  <Step title="Check browser console">
    Look for network errors or 401/403 responses
  </Step>

  <Step title="Enable debug mode">
    ```typescript theme={null}
    enableDebug: true,
    ```

    Check console for classification responses
  </Step>
</Steps>

### Queries not being detected

**Symptom**: No classification happening, no events

**Causes**:

1. Not on supported platform (Google Search, ChatGPT)
2. SDK not active on current page
3. Platform not enabled in configuration

**Solutions**:

<Accordion title="1. Test on supported platforms">
  Currently supported:

  * Google Search (google.com)
  * ChatGPT (chatgpt.com)

  Navigate to these sites and try shopping queries.
</Accordion>

<Accordion title="2. Check SDK is active">
  ```typescript theme={null}
  // In browser console
  console.log('SDK active:', !!getAiChatExtensionSdk());
  ```
</Accordion>

<Accordion title="3. Verify platform is enabled">
  Check your platformControls configuration:

  ```typescript theme={null}
  platformControls: {
    enableGoogle: true,   // Default: true
    enableChatGPT: false, // Default: false - enable if needed
  }
  ```
</Accordion>

## Browser-specific issues

### Firefox: Content script not loading

**Symptom**: Works in Chrome but not Firefox

**Cause**: Different manifest format or permissions

**Solution**:

Ensure Firefox-compatible manifest:

```json manifest.json theme={null}
{
  "manifest_version": 3,
  "permissions": ["tabs", "scripting"],
  "host_permissions": ["<all_urls>"],
  "browser_specific_settings": {
    "gecko": {
      "id": "your-extension-id@example.com"
    }
  }
}
```

### Safari: Styling issues

**Symptom**: Chat panel styling broken in Safari

**Cause**: Webkit-specific CSS differences

**Solution**:

Use broadly compatible CSS:

```typescript theme={null}
customStyles: {
  panelContainer: {
    backgroundColor: 'rgba(255, 255, 255, 0.98)',
  }
}
```

## Debugging tips

### Enable debug mode

Always start with debug mode when troubleshooting:

```typescript theme={null}
await initializeAiChatExtensionSdk('your-api-key', {
  enableDebug: true,  // Enables detailed console logging
  // ... other config
});
```

### Check SDK version

Verify you're using the latest SDK version:

```bash theme={null}
pnpm list @sleek/ai-chat-extension-sdk
```

Update to latest:

```bash theme={null}
pnpm update @sleek/ai-chat-extension-sdk
```

### Inspect SDK state

In browser console:

```typescript theme={null}
// Get SDK instance
const sdk = getAiChatExtensionSdk();

// Check if initialized
console.log('SDK initialized:', !!sdk);

// Manually trigger classification (for testing)
// Note: This is an internal API and may not be available
```

### Check browser console

Always check the DevTools Console for:

* JavaScript errors
* Network request failures
* SDK debug logs
* Warning messages

### Test in incognito mode

Test in incognito/private browsing to rule out:

* Conflicts with other extensions
* Cached data issues
* Profile-specific problems

### Inspect network requests

In DevTools Network tab, filter for:

* Requests to `chat.pie.org` (chat backend)
* Failed requests (red)
* 401/403 responses (authentication issues)

## Common error messages

### "Manifest validation failed"

**Error**: `Failed to initialize SDK: Manifest validation failed`

**Solution**: Fix manifest.json configuration (see [Manifest configuration issues](#manifest-configuration-issues))

### "Invalid API key"

**Error**: `Failed to classify query: 401 Unauthorized`

**Solution**: Verify API key is correct and active

## Getting help

If you're still experiencing issues:

<CardGroup cols={2}>
  <Card title="Email support" icon="envelope" href="mailto:support@onsleek.com">
    Contact our support team for assistance
  </Card>

  <Card title="Check documentation" icon="book" href="/ai-chat-sdk-reference/introduction">
    Review the full SDK documentation
  </Card>
</CardGroup>

When contacting support, please include:

* SDK version
* Browser and version
* Manifest.json content
* Console errors/logs
* Steps to reproduce the issue