Troubleshooting

Solutions to common issues when working with SmarterElements.

CDN Version Issues

Version Mismatch Problems

Symptoms:

Features not working as expected
Console errors about missing methods
Inconsistent behavior across environments

Solutions:

Check Loaded Version

// Verify which version is actually loaded
console.log('Loaded version:', SmarterElements.version);

// Compare with expected version
if (SmarterElements.version !== '1.2.3') {
  console.warn('Version mismatch detected');
}

Lock to Specific Version

<!-- ❌ Problematic - version can change unexpectedly -->
<script src="https://unpkg.com/@smarterservices/smarter-elements@latest/dist/smarter-elements.umd.js"></script>

<!-- ✅ Better - locked to specific version -->
<script src="https://unpkg.com/@smarterservices/smarter-elements@1.2.3/dist/smarter-elements.umd.js"></script>

Handle Version Compatibility

// Feature detection instead of version checking
if (typeof SmarterElements.prototype.openModal === 'function') {
  // Modal feature is available
  element.openModal(options);
} else {
  // Fallback for older versions
  element.mount('#container');
}

CDN Loading Issues

Symptoms:

Script fails to load
SmarterElements is not defined errors
Network timeouts

Solutions:

Add Fallback CDN

<!-- Primary CDN -->
<script src="https://unpkg.com/@smarterservices/smarter-elements@1.2.3/dist/smarter-elements.umd.js"></script>

<!-- Fallback CDN -->
<script>
  if (typeof SmarterElements === 'undefined') {
    document.write('<script src="https://cdn.jsdelivr.net/npm/@smarterservices/smarter-elements@1.2.3/dist/smarter-elements.umd.js"><\/script>');
  }
</script>

Add Loading Error Handling

<script 
  src="https://unpkg.com/@smarterservices/smarter-elements@1.2.3/dist/smarter-elements.umd.js"
  onerror="handleCDNError()"
></script>

<script>
  function handleCDNError() {
    console.error('Failed to load SmarterElements from CDN');
    // Show fallback UI or load from alternative source
    document.getElementById('fallback-message').style.display = 'block';
  }
</script>

Verify CDN Availability

// Check if CDN is accessible
fetch('https://unpkg.com/@smarterservices/smarter-elements@1.2.3/package.json')
  .then(response => response.json())
  .then(data => {
    console.log('Available version:', data.version);
  })
  .catch(error => {
    console.error('CDN not accessible:', error);
  });

Version Update Strategy

Best Practices:

Development Environment

<!-- Use latest for development -->
<script src="https://unpkg.com/@smarterservices/smarter-elements@latest/dist/smarter-elements.umd.js"></script>

Staging Environment

<!-- Test with specific version before production -->
<script src="https://unpkg.com/@smarterservices/smarter-elements@1.3.0/dist/smarter-elements.umd.js"></script>

Production Environment

<!-- Lock to tested version -->
<script src="https://unpkg.com/@smarterservices/smarter-elements@1.2.3/dist/smarter-elements.umd.js"></script>

Gradual Updates

<!-- Allow patch updates only -->
<script src="https://unpkg.com/@smarterservices/smarter-elements@~1.2.0/dist/smarter-elements.umd.js"></script>

Common Issues

Element Not Loading

Symptoms:

Element container remains empty
Console shows network errors
onError callback is triggered

Possible Causes & Solutions:

Incorrect Base URL

// ❌ Wrong
const elements = new SmarterElements({ baseUrl: '/wrong-path' });

// ✅ Correct
const elements = new SmarterElements({ baseUrl: '/elements' });

Element Type Not Found

// Check if element type exists
const element = elements.create('nonexistent/element', {
  onError: (error) => {
    if (error.code === 'ELEMENT_NOT_FOUND') {
      console.error('Element type does not exist');
    }
  }
});

Network Connectivity Issues

// Add timeout and retry logic
const elements = new SmarterElements({ 
  baseUrl: '/elements',
  timeout: 60000 // Increase timeout
});

Symptoms:

Modal overlay appears but content is empty
Modal doesn’t open at all
JavaScript errors in console

Solutions:

Check Modal Options

// Ensure valid modal options
await element.openModal({
  width: '80%',        // Valid CSS value
  maxWidth: '1000px',  // Valid CSS value
  zIndex: 1000         // Numeric value
});

Verify Element is Ready

const element = elements.create('element/type', {
  config: {},
  onReady: async () => {
    // Only open modal after element is ready
    await element.openModal(options);
  }
});

Check for Conflicting CSS

/* Ensure modal z-index is higher than other elements */
.modal-overlay {
  z-index: 1000 !important;
}

Auto-Resize Not Working

Symptoms:

Element content is cut off
Modal doesn’t adjust to content size
Fixed height despite auto-resize

Solutions:

Enable Auto-Resize

const element = elements.create('element/type', {
  config: {},
  autoResize: true, // Enable auto-resize
  onResize: (dimensions) => {
    console.log('New dimensions:', dimensions);
  }
});

Check Element Implementation

// Element should send resize messages
// This is handled automatically by SmarterElements framework

Verify Container Constraints

await element.openModal({
  width: '80%',
  maxHeight: '90vh', // Don't constrain height too much
  // Remove fixed height to allow auto-resize
});

Memory Leaks

Symptoms:

Browser becomes slow over time
Increasing memory usage
Elements not being cleaned up

Solutions:

Proper Element Cleanup

// Always destroy elements when done
useEffect(() => {
  const element = elements.create('type', config);
  
  return () => {
    element.destroy(); // Cleanup on unmount
  };
}, []);

Remove Event Listeners

const handler = (data) => console.log(data);

element.on('event', handler);

// Remove when done
element.off('event', handler);

Destroy All Elements

// When app unmounts or navigates away
elements.destroyAll();

Error Codes

ELEMENT_NOT_FOUND

Cause: Element type doesn’t exist or is misspelled. Solution:

// Check available element types
const availableTypes = [
  'blockkit/renderer',
  'proctoring/session-viewer',
  // ... other types
];

if (!availableTypes.includes(elementType)) {
  console.error(`Element type '${elementType}' is not available`);
}

LOAD_FAILED

Cause: Element failed to load due to server error or network issue. Solution:

const element = elements.create('element/type', {
  config: {},
  onError: (error) => {
    if (error.code === 'LOAD_FAILED') {
      // Retry after delay
      setTimeout(() => {
        element.mount('#container');
      }, 2000);
    }
  }
});

TIMEOUT

Cause: Element took too long to load. Solution:

// Increase timeout
const elements = new SmarterElements({ 
  baseUrl: '/elements',
  timeout: 60000 // 60 seconds
});

CONFIG_ERROR

Cause: Invalid configuration passed to element. Solution:

// Validate configuration before creating element
function validateConfig(config, schema) {
  // Add validation logic based on element schema
  if (!config.requiredParam) {
    throw new Error('Missing required parameter: requiredParam');
  }
}

try {
  validateConfig(config, elementSchema);
  const element = elements.create('element/type', { config });
} catch (error) {
  console.error('Configuration error:', error.message);
}

Performance Issues

Slow Element Loading

Symptoms:

Elements take a long time to appear
Poor user experience

Solutions:

Preload Critical Elements

// Preload elements that will be used soon
const preloadElement = (type, config) => {
  const element = elements.create(type, { config });
  // Don't mount yet, just create
  return element;
};

Use Loading States

function showLoadingState(container) {
  container.innerHTML = `
    <div class="loading">
      <div class="spinner"></div>
      <p>Loading element...</p>
    </div>
  `;
}

const element = elements.create('element/type', {
  config: {},
  onReady: () => {
    // Remove loading state
    container.querySelector('.loading')?.remove();
  }
});

showLoadingState(container);
element.mount(container);

Implement Element Pooling

// Reuse elements instead of creating new ones
class ElementPool {
  constructor(elementType, poolSize = 3) {
    this.pool = [];
    this.elementType = elementType;
    
    // Pre-create elements
    for (let i = 0; i < poolSize; i++) {
      this.pool.push(this.createElement());
    }
  }
  
  createElement() {
    return elements.create(this.elementType, {
      config: {}
    });
  }
  
  acquire() {
    return this.pool.pop() || this.createElement();
  }
  
  release(element) {
    // Reset element state
    element.postMessage({ type: 'reset' });
    this.pool.push(element);
  }
}

High Memory Usage

Solutions:

Limit Concurrent Elements

class ElementManager {
  constructor(maxElements = 10) {
    this.elements = [];
    this.maxElements = maxElements;
  }
  
  create(type, config) {
    // Remove oldest element if at limit
    if (this.elements.length >= this.maxElements) {
      const oldest = this.elements.shift();
      oldest.destroy();
    }
    
    const element = elements.create(type, config);
    this.elements.push(element);
    return element;
  }
}

Lazy Load Elements

// Only create elements when they're visible
const observer = new IntersectionObserver((entries) => {
  entries.forEach(entry => {
    if (entry.isIntersecting) {
      createElementForContainer(entry.target);
      observer.unobserve(entry.target);
    }
  });
});

document.querySelectorAll('.lazy-element').forEach(el => {
  observer.observe(el);
});

Browser Compatibility

Internet Explorer Issues

Note: SmarterElements requires modern browser features and doesn’t support Internet Explorer. Minimum Requirements:

Chrome 60+
Firefox 55+
Safari 12+
Edge 79+

Mobile Browser Issues

Common Issues:

Touch events not working
Modal sizing problems on mobile
Performance issues on older devices

Solutions:

Mobile-Optimized Modal Options

const isMobile = window.innerWidth < 768;

await element.openModal({
  width: isMobile ? '95%' : '80%',
  maxWidth: isMobile ? 'none' : '1000px',
  maxHeight: isMobile ? '90vh' : '80vh'
});

Touch Event Handling

// Elements automatically handle touch events
// No additional configuration needed

Development Issues

Hot Reload Problems

Symptoms:

Elements don’t update during development
Stale element instances

Solutions:

Clean Up on Hot Reload

// In development, clean up elements on module reload
if (module.hot) {
  module.hot.dispose(() => {
    elements.destroyAll();
  });
}

Force Element Refresh

// Add cache busting in development
const elements = new SmarterElements({
  baseUrl: '/elements',
  debug: process.env.NODE_ENV === 'development'
});

TypeScript Issues

Common Problems:

Type errors with element configuration
Missing type definitions

Solutions:

Extend Element Interfaces

interface MyElementConfig extends ElementConfig {
  customParam: string;
}

const element = elements.create<MyElementConfig>('my/element', {
  config: {
    customParam: 'value'
  }
});

Type Assertion for Dynamic Config

const config = dynamicConfig as ElementConfig;
const element = elements.create('element/type', { config });

Getting Help

Debug Information

When reporting issues, include:

Browser and Version
SmarterElements Version
Console Errors
Element Configuration
Reproduction Steps

Enable Debug Mode

const elements = new SmarterElements({
  baseUrl: '/elements',
  debug: true // Enables detailed logging
});

Collect Debug Information

// Get system information
const debugInfo = {
  userAgent: navigator.userAgent,
  elementsVersion: elements.version,
  activeElements: elements.getElements().length,
  lastError: elements.getLastError()
};

console.log('Debug Info:', debugInfo);

Contact Support

Documentation: SmarterElements Docs
GitHub Issues: Report a Bug
Email Support: support@smarterservices.com

Still having issues? Check our FAQ or reach out to our support team.

Getting Started

Guides

Element Reference

Troubleshooting

Troubleshooting

CDN Version Issues

Version Mismatch Problems

CDN Loading Issues

Version Update Strategy

Common Issues

Element Not Loading

Auto-Resize Not Working

Memory Leaks

Error Codes

ELEMENT_NOT_FOUND

LOAD_FAILED

TIMEOUT

CONFIG_ERROR

Performance Issues

Slow Element Loading

High Memory Usage

Browser Compatibility

Internet Explorer Issues

Mobile Browser Issues

Development Issues

Hot Reload Problems

TypeScript Issues

Getting Help

Debug Information

Enable Debug Mode

Collect Debug Information

Contact Support

Getting Started

Guides

Element Reference

​Troubleshooting

​CDN Version Issues

​Version Mismatch Problems

​CDN Loading Issues

​Version Update Strategy

​Common Issues

​Element Not Loading

​Modal Not Displaying

​Auto-Resize Not Working

​Memory Leaks

​Error Codes

​ELEMENT_NOT_FOUND

​LOAD_FAILED

​TIMEOUT

​CONFIG_ERROR

​Performance Issues

​Slow Element Loading

​High Memory Usage

​Browser Compatibility

​Internet Explorer Issues

​Mobile Browser Issues

​Development Issues

​Hot Reload Problems

​TypeScript Issues

​Getting Help

​Debug Information

​Enable Debug Mode

​Collect Debug Information

​Contact Support

Troubleshooting

CDN Version Issues

Version Mismatch Problems

CDN Loading Issues

Version Update Strategy

Common Issues

Element Not Loading

Modal Not Displaying

Auto-Resize Not Working

Memory Leaks

Error Codes

ELEMENT_NOT_FOUND

LOAD_FAILED

TIMEOUT

CONFIG_ERROR

Performance Issues

Slow Element Loading

High Memory Usage

Browser Compatibility

Internet Explorer Issues

Mobile Browser Issues

Development Issues

Hot Reload Problems

TypeScript Issues

Getting Help

Debug Information

Enable Debug Mode

Collect Debug Information

Contact Support