Troubleshooting

Common issues and solutions when integrating the VECU IDV Web SDK.

Common Issues

SDK failed to initialize

Cause: Invalid configuration or missing dependencies

Solutions:

• Check that deploymentStage is set correctly ('sandbox' or 'production')
• Verify bearerToken is provided and valid (required for all API calls)
• Check browser console for specific error messages
• Ensure you're using a supported browser version

// Verify configuration
const sdk = createVecuIDVSDK({
  deploymentStage: 'sandbox', // Must be 'sandbox' or 'production'
  bearerToken: 'your-token', // Required - check it's not undefined
  debug: true, // Enable for detailed logging
});

Network request failed

Cause: Connection issues or CORS problems

Solutions:

• Check internet connection stability
• Verify bearerToken is provided (missing token causes 401 errors)
• Verify your domain is allowlisted for CORS
• Try increasing the timeout configuration
• Check if firewall/proxy is blocking requests

const sdk = createVecuIDVSDK({
  deploymentStage: 'sandbox',
  bearerToken: 'your-token',
  timeout: 60000, // Increase timeout to 60 seconds
  maxRetries: 5, // Increase retry attempts
});

Verification UI not loading

Cause: Container issues or styling conflicts

Solutions:

• Ensure container element exists and is visible
• Set container min-height to at least 600px
• Check for CSS conflicts affecting the container
• Try clearing the container before initialization

<!-- Ensure proper container setup -->
<div id="verification-container" style="min-height: 600px; width: 100%;"></div>

// Clear container before starting
const container = document.getElementById('verification-container');
container.innerHTML = '';

await sdk.startVerificationWithCustomer(container, {
  /* ... */
});

TOKEN_EXCHANGE_FAILED error

Cause: Bearer token is invalid or expired

Solutions:

• Verify the bearer token is current and valid
• Check that the token hasn't expired
• Refresh the token and call updateConfig

// Handle token refresh
sdk.on(SdkEvent.AUTHENTICATION_TOKEN_FAILURE, async () => {
  const newToken = await refreshBearerToken();
  await sdk.updateConfig({ bearerToken: newToken });
});

Webhooks not being received

Cause: Webhook configuration or endpoint issues

Solutions:

• Verify webhook URL is publicly accessible
• Ensure endpoint returns 200 status code
• Check webhook authentication configuration
• Test endpoint with tools like ngrok for local development

See the Webhooks Guide for complete setup instructions.

Verification stuck at loading

Cause: Provider SDK failed to load or initialize

Solutions:

• Check for ad blockers or script blockers
• Verify network connectivity
• Check browser console for blocked scripts
• Try a different browser

sdk.on(SdkEvent.PROVIDER_ERROR, event => {
  console.error('Provider failed to load:', event.data);
});

Provider-Specific Issues

Verification timeout (VERIFICATION_FAILED)

Cause: The verification session exceeded its maximum duration.

Solutions:

• User may have abandoned the flow — restart verification
• Check if user's session expired
• Verify network connectivity

sdk.on(SdkEvent.VERIFICATION_FAILED, event => {
  if (event.data.error?.code === 'VERIFICATION_TIMEOUT') {
    console.log('Verification timed out — user may have abandoned the flow');
  }
});

Verification UI not loading in iframe

Cause: Network issues or browser permissions

Solutions:

• Check camera and microphone permissions in browser
• Verify network connectivity
• Check Content Security Policy allows the verification iframe source
• Clear browser cache and retry

sdk.on(SdkEvent.UI_READY, () => {
  console.log('Verification UI loaded successfully');
});

Camera/microphone access denied

Cause: User denied permissions or permissions not requested

Solutions:

• The verification process may require camera access for biometric verification
• Prompt user to allow camera access in browser settings
• Check browser permissions API for status

Error Code Reference

Validation Errors

User Action Errors

Authentication Errors

System Errors

Debug Mode

Enable debug mode for detailed logging:

const sdk = createVecuIDVSDK({
  deploymentStage: 'sandbox',
  bearerToken: 'your-bearer-token',
  debug: true,
  logLevel: 'debug', // Show all log messages
});

// Debug information will appear in browser console
// Look for messages prefixed with [VECU-SDK]

Debug mode provides:

• Detailed logging of SDK operations
• API request/response logging
• User interaction events
• Provider event forwarding

Browser Developer Tools

Network Tab

Check for failed requests:

1. Open Developer Tools (F12)
2. Go to Network tab
3. Filter by "XHR" or "Fetch"
4. Look for red (failed) requests
5. Check request/response details

Console Tab

Look for SDK errors:

1. Open Developer Tools (F12)
2. Go to Console tab
3. Filter by "Error" or search for "VECU"
4. Note any error messages

Application Tab

Check stored data:

1. Open Developer Tools (F12)
2. Go to Application tab
3. Check Local Storage and Session Storage
4. Look for SDK-related keys

Framework-Specific Issues

React: Memory Leaks

Issue: Component re-renders cause multiple SDK instances

Solution: Store SDK in a ref and cleanup properly:

const sdkRef = useRef<VecuIDVSDK | null>(null);

useEffect(() => {
  sdkRef.current = createVecuIDVSDK({
    /* ... */
  });

  return () => {
    sdkRef.current?.destroy();
  };
}, []); // Empty deps - only create once

Vue: Reactivity Issues

Issue: SDK instance becomes reactive causing issues

Solution: Use shallowRef or keep SDK outside reactive system:

// Don't make SDK reactive
let sdk: VecuIDVSDK | null = null;

onMounted(() => {
  sdk = createVecuIDVSDK({
    /* ... */
  });
});

Next.js: SSR Errors

Issue: SDK fails during server-side rendering

Solution: Use dynamic imports with ssr: false:

const VerificationComponent = dynamic(() => import('./VerificationComponent'), {
  ssr: false,
});

Performance Optimization

Lazy Loading

Load the SDK only when needed:

const loadSDK = async () => {
  const { createVecuIDVSDK } = await import('vec-idp-web-sdk');
  return createVecuIDVSDK({
    deploymentStage: 'sandbox',
    bearerToken: process.env.BEARER_TOKEN,
    debug: process.env.NODE_ENV === 'development',
  });
};

// Only load when verification starts
const handleStartVerification = async () => {
  const sdk = await loadSDK();
  // ... use sdk
};

Instance Reuse

Reuse SDK instance across verifications:

// Create once
const sdk = createVecuIDVSDK({
  /* ... */
});

// Reuse for multiple verifications
await sdk.startVerificationWithCustomer(container1, {
  /* ... */
});
// Later...
await sdk.startVerificationWithCustomer(container2, {
  /* ... */
});

Browser Support

Supported Browsers

Not Supported

• Internet Explorer (all versions)
• Safari < 14
• Chrome < 88
• Firefox < 78

Getting Help

If you're still experiencing issues:

1. Check the changelog - Your issue may be fixed in a newer version
2. Search existing issues - Someone may have encountered the same problem
3. Enable debug mode - Gather detailed logs before reporting
4. Contact support - Provide logs, browser info, and reproduction steps

Next Steps

• API Reference - Complete method reference
• Events - Handle SDK events
• Testing - Test your integration