Troubleshooting Guide

Overview

This guide helps you diagnose and resolve common issues when integrating and using the FAD SDK. Each section includes the problem description, possible causes, and step-by-step solutions.

Installation Issues

npm install fails with authentication error

Problem: Cannot install @fad-producto/fad-sdk from npm registry.Possible Causes:

Missing or invalid npm authentication
Private package access not configured
Network/firewall restrictions

Solution:

Verify npm authentication

Check if you have access to the private registry:

npm whoami

Configure npm registry

If using a private registry, configure authentication:

npm config set registry https://your-registry-url
npm login

Check package availability

Verify the package exists and you have access:

npm view @fad-producto/fad-sdk

Module not found after installation

Problem: Import fails with “Module not found: @fad-producto/fad-sdk”Solution:

Verify the package is installed:
```
npm list @fad-producto/fad-sdk
```

Clear node_modules and reinstall:

rm -rf node_modules package-lock.json
npm install

For TypeScript projects, ensure node_modules is not excluded in tsconfig.json:

{
  "compilerOptions": {
    "moduleResolution": "node"
  }
}

Integration Issues

ES6 module import not working in vanilla JS

Problem: Uncaught SyntaxError: Cannot use import statement outside a moduleCause: Missing type="module" attribute in script tag.Solution:Add type="module" to your script tag:

<!-- ❌ Wrong -->
<script src="app.js"></script>

<!-- ✅ Correct -->
<script src="app.js" type="module"></script>

ES6 modules require a server environment. Opening HTML files directly with file:// protocol will fail due to CORS restrictions.

CORS error when loading SDK files

Problem: Access to script at 'file://...' from origin 'null' has been blocked by CORS policyCause: Attempting to load ES6 modules using file:// protocol.Solution:Use a local development server:

# Install Live Server extension
# Right-click HTML file → "Open with Live Server"

SDK initialization fails immediately

Problem: SDK constructor throws an error or returns undefined.Possible Causes:

Invalid or expired authentication token
Incorrect environment configuration
Network connectivity issues

Solution:

Verify token is valid and not expired:

console.log('Token:', TOKEN); // Should not be empty

Check environment configuration:

const options = {
  environment: FadSDK.getFadEnvironments().UATHA, // or PRODUCTION
};
console.log('Environment:', options.environment);

Add error handling:

try {
  const FAD_SDK = new FadSDK(TOKEN, options);
  console.log('SDK initialized successfully');
} catch (error) {
  console.error('Initialization error:', error);
}

Camera and Permissions Issues

Camera not working - CAMERA_NOT_RUNNING error

Problem: Error code CAMERA_NOT_RUNNING when starting camera-based modules.Possible Causes:

Camera permissions denied
Camera in use by another application
Browser doesn’t support getUserMedia
Device has no camera

Solution:

Check browser compatibility

Verify your browser supports getUserMedia:

if (!navigator.mediaDevices || !navigator.mediaDevices.getUserMedia) {
  alert('Your browser does not support camera access');
}

Request camera permissions

Test camera access before initializing SDK:

async function testCamera() {
  try {
    const stream = await navigator.mediaDevices.getUserMedia({ 
      video: true 
    });
    console.log('Camera access granted');
    stream.getTracks().forEach(track => track.stop());
    return true;
  } catch (err) {
    console.error('Camera access denied:', err);
    return false;
  }
}

Handle permission errors

catch (ex) {
  if (ex.code === FadSDK.Errors.Facetec.Session.CAMERA_NOT_RUNNING) {
    alert('Camera not available. Please:\n' +
          '1. Grant camera permissions\n' +
          '2. Ensure no other app is using the camera\n' +
          '3. Try refreshing the page');
  }
}

For HTTPS requirements: Most browsers require HTTPS to access camera (except for localhost).

Camera permission denied on first load

Problem: Browser blocks camera access without showing permission prompt.Cause: Previous permission denial or browser security settings.Solution:

Clear site permissions in browser:
- Chrome: Settings → Privacy → Site Settings → Camera
- Firefox: Settings → Privacy → Permissions → Camera
- Safari: Settings → Websites → Camera

Implement permission checking:

async function checkCameraPermission() {
  try {
    const result = await navigator.permissions.query({ name: 'camera' });
    
    if (result.state === 'denied') {
      showPermissionHelp(); // Guide user to enable permissions
      return false;
    }
    
    return true;
  } catch (err) {
    // Fallback: Try to request access directly
    return testCamera();
  }
}

Camera works on desktop but not mobile

Problem: Camera functions correctly on desktop browsers but fails on mobile devices.Possible Causes:

HTTP instead of HTTPS (required on mobile)
Browser compatibility issues
Mobile OS permissions

Solution:

Use HTTPS: Mobile browsers require HTTPS for camera access

✅ https://your-domain.com
✅ https://localhost (development)
❌ http://your-domain.com (won't work on mobile)

Check mobile browser support:
- iOS Safari 11+
- Chrome Mobile 53+
- Samsung Internet 6.2+
Test on multiple devices:
- Different mobile browsers
- Different OS versions
- Both iOS and Android

Module-Specific Issues

Document capture: ID_PHOTO_NOT_FOUND error

Problem: Error code ID_PHOTO_NOT_FOUND when capturing identification documents.Cause: Face photo extraction failed from the captured document.Solution:

Verify idPhoto parameter

Ensure the idPhoto parameter is set correctly:

const idPhoto = true; // Enable face extraction
const response = await FAD_SDK.startRegula(
  CREDENTIALS,
  FadSDK.Constants.Regula.CaptureType.CAMERA_SNAPSHOT,
  true,    // idData
  idPhoto, // idPhoto extraction
  CONFIGURATION
);

Improve capture conditions

Guide users to:

Ensure good lighting
Avoid glare on the document
Keep the document flat and fully visible
Use a contrasting background

Handle gracefully

catch (ex) {
  if (ex.code === FadSDK.Errors.Regula.ID_PHOTO_NOT_FOUND) {
    showRetryMessage(
      'Could not extract photo from ID. Please:\n' +
      '• Ensure the photo on ID is clearly visible\n' +
      '• Improve lighting conditions\n' +
      '• Avoid shadows or glare on the document'
    );
  }
}

Document capture: OCR_NOT_FOUND error

Problem: Error code OCR_NOT_FOUND - OCR data extraction failed.Cause: Text on the document could not be read clearly.Solution:

Verify OCR is enabled:

const idData = true; // Must be true for OCR
const response = await FAD_SDK.startRegula(
  CREDENTIALS,
  FadSDK.Constants.Regula.CaptureType.CAMERA_SNAPSHOT,
  idData, // Enable OCR extraction
  true,
  CONFIGURATION
);

Improve capture quality:
- Better lighting (avoid shadows)
- Higher resolution camera
- Hold camera steady
- Ensure text is in focus
- Clean the camera lens

User guidance:

catch (ex) {
  if (ex.code === FadSDK.Errors.Regula.OCR_NOT_FOUND) {
    showCaptureGuide({
      title: 'Document Not Clear',
      instructions: [
        'Hold the device steady',
        'Ensure good lighting',
        'Keep text sharp and readable',
        'Avoid glare and shadows'
      ]
    });
  }
}

Liveness detection: INITIALIZATION_NOT_COMPLETED error

Problem: Error code INITIALIZATION_NOT_COMPLETED during liveness check.Possible Causes:

Network connectivity issues
Server-side initialization failure
Invalid credentials
Timeout during initialization

Solution:

Implement retry logic:

async function startLivenessWithRetry(maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const FAD_SDK = new FadSDK(TOKEN, options);
    try {
      return await FAD_SDK.startFacetec(CREDENTIALS, CONFIG);
    } catch (ex) {
      if (ex.code === FadSDK.Errors.Facetec.Session.INITIALIZATION_NOT_COMPLETED) {
        if (i < maxRetries - 1) {
          console.log(`Retry ${i + 1}/${maxRetries}`);
          await new Promise(r => setTimeout(r, 1000));
          continue;
        }
      }
      throw ex;
    } finally {
      FAD_SDK.end();
    }
  }
}

Check network connectivity:

if (!navigator.onLine) {
  alert('No internet connection. Please check your network.');
  return;
}

Verify credentials:

console.log('Credentials:', CREDENTIALS); // Ensure not empty

Signature module: Video recording fails

Problem: Signature capture completes but video files are missing or corrupted.Possible Causes:

Browser doesn’t support MediaRecorder
Insufficient device storage
Memory limitations

Solution:

Check MediaRecorder support:

if (!window.MediaRecorder) {
  alert('Video recording not supported on this browser');
  return;
}

Handle video data properly:

const signatureResponse = await FAD_SDK.startSignature(CONFIG);

// Create object URLs
const faceVideoUrl = URL.createObjectURL(
  signatureResponse.data.videoFace
);
const signatureVideoUrl = URL.createObjectURL(
  signatureResponse.data.videoSignature
);

// Use the videos
document.getElementById('face-video').src = faceVideoUrl;

// Clean up when done
setTimeout(() => {
  URL.revokeObjectURL(faceVideoUrl);
  URL.revokeObjectURL(signatureVideoUrl);
}, 60000);

Check browser compatibility:
- Chrome 49+
- Firefox 29+
- Safari 14.1+
- Edge 79+

Performance Issues

SDK loads slowly or times out

Problem: SDK initialization takes too long or times out.Possible Causes:

Large SDK bundle size
Slow network connection
Server-side delays
Resource loading issues

Solution:

Implement lazy loading:

// Load SDK only when needed
let FadSDK;

async function loadSDK() {
  if (!FadSDK) {
    FadSDK = (await import('@fad-producto/fad-sdk')).default;
  }
  return FadSDK;
}

button.addEventListener('click', async () => {
  const SDK = await loadSDK();
  const FAD_SDK = new SDK(TOKEN, options);
  // Continue...
});

Show loading indicator:

const loader = showLoader('Initializing SDK...');

try {
  const FAD_SDK = new FadSDK(TOKEN, options);
  loader.updateMessage('Starting process...');
  const response = await FAD_SDK.startFacetec(CREDENTIALS, CONFIG);
} finally {
  loader.hide();
}

Optimize network:
- Use CDN for SDK files
- Enable HTTP/2
- Implement service worker caching

Memory leaks after multiple module runs

Problem: Browser becomes slow or crashes after using SDK multiple times.Cause: SDK resources not properly cleaned up.Solution:

Always call end():

const FAD_SDK = new FadSDK(TOKEN, options);
try {
  await FAD_SDK.startFacetec(CREDENTIALS, CONFIG);
} finally {
  FAD_SDK.end(); // CRITICAL: Always cleanup
}

Revoke object URLs:

const videoUrl = URL.createObjectURL(videoBlob);
// Use the URL...

// Clean up when done
URL.revokeObjectURL(videoUrl);

Clear references:

let FAD_SDK = new FadSDK(TOKEN, options);
try {
  // Use SDK
} finally {
  FAD_SDK.end();
  FAD_SDK = null; // Clear reference
}

Runtime Errors

WebAssembly compilation failed

Problem: WebAssembly.instantiate(): Compiling function failedCause: Browser doesn’t support WebAssembly or WASM features used by SDK.Solution:

Check WebAssembly support:

if (typeof WebAssembly !== 'object') {
  alert('Your browser does not support WebAssembly.\n' +
        'Please update your browser or use a modern browser.');
  return;
}

Minimum browser versions:
- Chrome 57+
- Firefox 52+
- Safari 11+
- Edge 16+

Fallback for unsupported browsers:

const isWasmSupported = (() => {
  try {
    if (typeof WebAssembly === 'object') {
      return true;
    }
  } catch (e) {}
  return false;
})();

if (!isWasmSupported) {
  showUnsupportedBrowserMessage();
  return;
}

Uncaught TypeError: FAD_SDK.end is not a function

Problem: Error when calling FAD_SDK.end().Cause: SDK instance was not initialized correctly or already disposed.Solution:

Check initialization:

const FAD_SDK = new FadSDK(TOKEN, options);

if (!FAD_SDK) {
  console.error('SDK initialization failed');
  return;
}

Verify SDK import:

import FadSDK from '@fad-producto/fad-sdk';

// Verify it's a constructor
console.log(typeof FadSDK); // Should be "function"

Avoid double cleanup:

let isCleanedUp = false;

try {
  // SDK operations
} finally {
  if (!isCleanedUp) {
    FAD_SDK.end();
    isCleanedUp = true;
  }
}

Deployment Issues

SDK works locally but fails in production

Problem: SDK works in development but fails when deployed.Possible Causes:

HTTP instead of HTTPS in production
Missing environment variables
CORS issues
Different browser usage patterns

Solution:

Ensure HTTPS:

✅ https://your-domain.com
❌ http://your-domain.com (camera won't work)

Check environment configuration:

const options = {
  environment: process.env.NODE_ENV === 'production'
    ? FadSDK.getFadEnvironments().PRODUCTION
    : FadSDK.getFadEnvironments().UATHA,
};

Verify token and credentials:

if (!TOKEN) {
  console.error('Missing SDK token in production');
}

Enable error tracking:

catch (ex) {
  // Log to error tracking service
  errorTracker.captureException(ex, {
    context: { module: 'fad-sdk', environment: 'production' }
  });
}

Getting More Help

If you’re still experiencing issues after trying these solutions:

Best Practices

Review SDK best practices

API Reference

Check API documentation

NPM Integration

NPM integration guide

Vanilla JS Integration

Vanilla JS integration guide

For module-specific error codes and detailed troubleshooting, consult the individual module documentation.

Getting Started

Core Concepts

Modules

Integration Guides

Troubleshooting Guide

Overview

Installation Issues

Integration Issues

Camera and Permissions Issues

Module-Specific Issues

Performance Issues

Runtime Errors

Deployment Issues

Getting More Help

Best Practices

API Reference

NPM Integration

Vanilla JS Integration

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Modules

Integration Guides

​Overview

​Installation Issues

​Integration Issues

​Camera and Permissions Issues

​Module-Specific Issues

​Performance Issues

​Runtime Errors

​Deployment Issues

​Getting More Help

Best Practices

API Reference

NPM Integration

Vanilla JS Integration

Build docs developers (and LLMs) love

Overview

Installation Issues

Integration Issues

Camera and Permissions Issues

Module-Specific Issues

Performance Issues

Runtime Errors

Deployment Issues

Getting More Help