Skip to main content

Troubleshooting Connect UI

This guide helps you resolve common issues when integrating Connect UI.

Common Issues​

Service Key Generation Fails​

401 Unauthorized Error​

{
  "error": "Unauthorized",
  "message": "Invalid API key"
}

Solution:

  • Verify your API key is correct
  • Check if the API key has the required permissions
  • Ensure you're using the correct environment (production vs. staging)
// Check API key format
const apiKey = process.env.UNIZO_API_KEY;
if (!apiKey || !apiKey.startsWith('sk_')) {
  throw new Error('Invalid API key format');
}

422 Validation Error​

{
  "error": "Validation failed",
  "details": {
    "subOrganization.externalKey": "Required field"
  }
}

Solution: Check all required fields are present:

const requestBody = {
  type: "INTEGRATION_TOKEN",
  name: "my-integration",
  subOrganization: {
    name: "Customer Name",
    externalKey: "unique-customer-id" // Required!
  },
  integration: {
    type: "GENERIC",
    target: {
      type: "Category",
      categorySelectors: [
        { type: "SCM" }
      ]
    }
  }
};

Iframe Not Loading​

Blank Iframe​

Possible causes:

  1. Invalid service key
  2. CSP blocking the iframe
  3. Service key expired

Debug steps:

// 1. Check browser console for errors
console.log('Service key:', serviceKey);

// 2. Test the URL directly
window.open(`https://dock.unizo.ai/links/${serviceKey}`);

// 3. Check CSP headers
const csp = document.querySelector('meta[http-equiv="Content-Security-Policy"]');
console.log('CSP:', csp?.content);

CORS or CSP Errors​

Refused to frame 'https://dock.unizo.ai' because an ancestor violates the following Content Security Policy directive: "frame-ancestors 'self'"

Solution: Update your CSP headers:

<meta http-equiv="Content-Security-Policy" 
      content="frame-src https://dock.unizo.ai;">

Or in your server headers:

app.use((req, res, next) => {
  res.setHeader(
    'Content-Security-Policy',
    "frame-src https://dock.unizo.ai;"
  );
  next();
});

Authentication Issues​

Provider Not Showing​

Possible causes:

  1. Category not enabled in your account
  2. Provider not available for the category
  3. Filtered by configuration

Debug:

// Check enabled categories
const response = await fetch('https://api.unizo.ai/v1/account/categories', {
  headers: { 'apikey': API_KEY }
});
const categories = await response.json();
console.log('Enabled categories:', categories);

OAuth Redirect Fails​

Error: "Invalid redirect URI"

Solution: Ensure your OAuth app is configured correctly:

  1. Check redirect URI matches exactly
  2. Include trailing slashes if required
  3. Use HTTPS in production

PostMessage Communication​

Not Receiving Messages​

// Debug postMessage
window.addEventListener('message', (event) => {
  console.log('Message received:', {
    origin: event.origin,
    data: event.data
  });
});

// Ensure iframe is loaded
const iframe = document.querySelector('iframe');
iframe.addEventListener('load', () => {
  console.log('Iframe loaded successfully');
});

Message Validation Errors​

// Add comprehensive logging
window.addEventListener('message', (event) => {
  try {
    if (event.origin !== 'https://dock.unizo.ai') {
      console.warn('Invalid origin:', event.origin);
      return;
    }
    
    console.log('Valid message:', event.data);
    
    if (!event.data.type) {
      console.error('Missing message type');
      return;
    }
    
    // Process message
  } catch (error) {
    console.error('Message processing error:', error);
  }
});

Debugging Tools​

Enable Debug Mode​

Add debug parameter to get detailed logs:

const debugUrl = `https://dock.unizo.ai/links/${serviceKey}?debug=true`;

Network Inspector​

Monitor API calls:

// Log all API calls
const originalFetch = window.fetch;
window.fetch = function(...args) {
  console.log('API Call:', args[0]);
  return originalFetch.apply(this, args)
    .then(response => {
      console.log('Response:', response.status);
      return response;
    });
};

Browser DevTools​

  1. Network Tab: Check for failed requests
  2. Console: Look for JavaScript errors
  3. Elements: Verify iframe is rendering
  4. Application: Check localStorage/cookies

Error Recovery​

Implement Retry Logic​

async function generateServiceKeyWithRetry(maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await generateServiceKey();
    } catch (error) {
      console.error(`Attempt ${i + 1} failed:`, error);
      if (i === maxRetries - 1) throw error;
      
      // Exponential backoff
      await new Promise(resolve => 
        setTimeout(resolve, Math.pow(2, i) * 1000)
      );
    }
  }
}

User-Friendly Error Messages​

function getErrorMessage(error) {
  const errorMessages = {
    401: 'Authentication failed. Please contact support.',
    403: 'Access denied. Please check your permissions.',
    429: 'Too many requests. Please try again later.',
    500: 'Server error. Please try again.',
  };
  
  return errorMessages[error.status] || 'An unexpected error occurred.';
}

Getting Help​

If you're still experiencing issues:

  1. Check the browser console for detailed error messages
  2. Review the integration guide to ensure correct implementation
  3. Contact support with:
    • Error messages and screenshots
    • Browser/environment details
    • Steps to reproduce
    • Request/response logs (sanitized)

Support Channels​