Skip to main content

Troubleshooting

Common issues and solutions for the Knidian SDK.

Installation Issues​

CDN Script Not Loading​

Symptoms: SDK script fails to load from CDN

Causes:

  • Network/firewall blocking CDN
  • Incorrect CDN URL
  • CORS issues

Solutions:

  1. Verify CDN URL:

    <!-- Correct URL -->
    <script src="https://cdn.knidian.ai/sdk/v1/knidian-sdk.min.js"></script>

  2. Check browser console for specific error messages

  3. Test CDN accessibility:

    curl https://cdn.knidian.ai/sdk/v1/knidian-sdk.min.js

  4. Whitelist CDN in firewall: cdn.knidian.ai

Initialization Issues​

"Authentication Failed" Error​

Symptoms: SDK fails to initialize with authentication error

Causes:

  • Backend auth endpoint not reachable
  • Session token generation failing
  • API key incorrect in backend
  • Network/CORS issues

Solutions:

  1. Verify auth endpoint is running:

    curl -X POST https://your-backend.com/api/knidian-auth \
      -H "Content-Type: application/json" \
      -d '{"userId": "test-user"}'

  2. Check backend API key (in your backend code):

    // Backend .env file should have:
    // KNIDIAN_API_KEY=kn_live_... (for production)
    // KNIDIAN_API_KEY=kn_test_... (for testing)

  3. Verify CORS is configured to allow your frontend origin

  4. Contact support to verify/rotate API key: licensing@knidian.ai

Container Not Found​

Symptoms: SDK doesn't render, console shows "Container not found"

Causes:

  • DOM element doesn't exist
  • Initializing before DOM is ready
  • Incorrect selector

Solutions:

  1. Verify element exists:

    const container = document.getElementById('knidian-container');
    console.log(container); // Should not be null

  2. Initialize after DOM loads:

    // Vanilla JS
    document.addEventListener('DOMContentLoaded', () => {
      const sdk = KnidianSDK.create({ /* ... */ });
    });

    // React
    useEffect(() => {
      const sdk = KnidianSDK.create({ /* ... */ });
      return () => sdk.destroy();
    }, []);

  3. Check selector syntax:

    // ID selector
    container: '#knidian-container'  // Element with id="knidian-container"

    // Class selector
    container: '.knidian-container' // Element with class="knidian-container"

    // DOM element
    container: document.getElementById('knidian-container')

Runtime Issues​

SDK Not Displaying Content​

Symptoms: SDK initializes but shows blank screen

Causes:

  • CSS conflicts
  • Z-index issues
  • Container size is zero
  • Theme configuration issues

Solutions:

  1. Check container dimensions:

    const container = document.getElementById('knidian-container');
    console.log(container.offsetWidth, container.offsetHeight);
    // Both should be > 0

  2. Set minimum container size:

    #knidian-container {
      min-height: 600px;
      width: 100%;
    }

  3. Check for CSS conflicts:

    // Use browser DevTools to inspect elements
    // Look for conflicting styles

  4. Reset to default theme:

    const sdk = KnidianSDK.create({
      authUrl: 'https://your-backend.com/api/knidian-auth',
      userId: 'user-123',
      container: '#app'
      // Remove theme config to test with defaults
    });

Theming Issues​

Custom Theme Not Applying​

Symptoms: Custom colors/fonts not showing

Causes:

  • Invalid color format
  • CSS specificity issues
  • Caching

Solutions:

  1. Verify color format:

    theme: {
      primaryColor: '#3b82f6' // Must be 6-digit hex
    }

  2. Clear browser cache

  3. Inspect element in DevTools to verify styles applied

Getting Help​

Before Contacting Support​

Gather this information:

  1. SDK Version: KnidianSDK.version
  2. Browser: Name and version
  3. Error Messages: From browser console
  4. Steps to Reproduce: Detailed steps
  5. Screenshots: If applicable
  6. Network Logs: From DevTools Network tab

Contact Support​

Response Times​

  • Standard support: 24 hours
  • Priority support: 4 hours
  • Critical issues: 1 hour

Additional Resources​

If your issue isn't listed here, please contact support@knidian.ai with detailed information about your problem.