CDN SDK
Troubleshooting
Common issues and solutions
Icons Not Showing
Check console for errors
Open browser DevTools and look for SDK error messages.
Verify icon names
// Get list of available icons
const icons = IconSDK.getAvailableIcons()
console.log(icons)
// Check specific icon
console.log(IconSDK.hasIcon('home')) // → true or falseConfirm SDK loaded
console.log(IconSDK.version) // Should print version number
console.log(IconSDK) // Should print SDK objectCheck project slug
Make sure the script URL has the correct project slug:
<!-- Correct -->
<script src="https://cdn.icon.dev/id-your-project/sdk.min.js"></script>
<!-- Wrong -->
<script src="https://cdn.icon.dev/id-wrong-slug/sdk.min.js"></script>Cache Issues
Clear cache and reload
IconSDK.clearCache()
IconSDK.reload()Hard refresh browser
- Chrome/Edge: Ctrl+Shift+R (Windows) or Cmd+Shift+R (Mac)
- Firefox: Ctrl+F5 (Windows) or Cmd+Shift+R (Mac)
- Safari: Cmd+Option+R (Mac)
Disable browser cache (development only)
In Chrome DevTools:
- Open Network tab
- Check "Disable cache"
- Keep DevTools open
Only use this during development. Don't forget to re-enable caching.
Performance Issues
Preload critical icons
// Preload icons above the fold
IconSDK.preload(['logo', 'menu', 'close', 'home'])Check network tab
- Open DevTools Network tab
- Filter by "svg"
- Look for:
- 404 errors (icon not found)
- Slow requests (network issues)
- Failed requests (CORS or permissions)
Reduce icon count
If loading many icons at once:
// Pause observer during bulk operations
IconSDK.stopObserver()
// Add icons
// ... your code ...
// Resume
IconSDK.init()
IconSDK.startObserver()Icons Look Wrong
Check for conflicting CSS
/* Your global styles might be affecting icons */
i {
font-style: normal !important; /* Don't use !important */
}
svg {
width: 100%; /* This can break icon sizing */
}Inspect the rendered SVG
const icon = document.querySelector('[data-icon="home"]')
console.log(icon.innerHTML) // Check SVG contentVerify attributes
<!-- Check that attributes are applied -->
<i data-icon="home" data-icon-size="24" data-icon-color="#000"></i>CORS Errors
Check browser console
If you see CORS errors, it usually means:
- Wrong domain: The SDK is loaded from a different domain
- Mixed content: Using HTTP on HTTPS page
- Blocked by policy: Corporate firewall or browser extension
Solutions
<!-- Ensure HTTPS on secure pages -->
<script src="https://cdn.icon.dev/id-project/sdk.min.js"></script>
<!-- Not HTTP -->
<script src="http://cdn.icon.dev/id-project/sdk.min.js"></script>Icons Not Updating
Clear cache after icon changes
After updating icons in the dashboard:
IconSDK.clearCache()
IconSDK.reload()Wait for cache expiration
Browser cache expires after 24 hours. Changes will appear automatically after that.
Check icon version in dashboard
Verify the icon was actually updated in your project dashboard.
MutationObserver Not Working
Check if observer is running
// Check observer status
if (IconSDK._config.observer) {
console.log('Observer is active')
} else {
console.log('Observer is stopped')
IconSDK.startObserver()
}Restart observer
IconSDK.stopObserver()
IconSDK.startObserver()Browser Compatibility
Minimum requirements
- Chrome/Edge: Latest 2 versions
- Firefox: Latest 2 versions
- Safari: Latest 2 versions
- Mobile: iOS Safari 12+, Chrome Android
Required features
- Fetch API
- Promises
- MutationObserver
Check compatibility
if (!window.fetch) {
console.error('Fetch API not supported')
}
if (!window.MutationObserver) {
console.error('MutationObserver not supported')
}Still Having Issues?
Contact support at support@icon.dev with:
- Browser and version
- Console error messages
- Example code or screenshot
- Project slug
Next Steps
- JavaScript API - Full API reference
- Best Practices - Performance tips