icon.dev
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 false

Confirm SDK loaded

console.log(IconSDK.version)  // Should print version number
console.log(IconSDK)  // Should print SDK object

Check 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:

  1. Open Network tab
  2. Check "Disable cache"
  3. 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

  1. Open DevTools Network tab
  2. Filter by "svg"
  3. 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 content

Verify 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:

  1. Wrong domain: The SDK is loaded from a different domain
  2. Mixed content: Using HTTP on HTTPS page
  3. 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