Skip to main content

Troubleshooting

Common issues and their solutions when working with the Vertical Template.

Setup Issues​

"Module not found" Errors​

Symptom: Build fails with module resolution errors.

Solution:

# Clear node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

Port 3000 Already in Use​

Symptom: "Port 3000 is already in use" error.

Solution:

# Kill process on port 3000
npx kill-port 3000

# Or use a different port
npm run dev -- -p 3001

Environment Variables Not Loading​

Symptom: App can't find environment variables.

Checklist:

  • File is named .env.local (not .env)
  • No syntax errors in file
  • Restart dev server after changes
  • Variables match expected names exactly

Authentication Issues​

"Invalid client secret" Error​

Cause: Entra ID client secret expired or incorrect.

Solution:

  1. Go to Azure Portal → Entra ID → App registrations
  2. Check Certificates & secrets
  3. Create new secret if expired
  4. Update .env.local with new value
  5. Restart dev server

"Invalid redirect URI" Error​

Cause: Redirect URI doesn't match Entra registration.

Solution:

  1. Verify redirect URI in Azure Portal matches exactly: 
    http://localhost:3000/api/auth/callback/azure-ad
  2. Include port number
  3. Use http:// for localhost (not https://)

401 Unauthorized from API​

Causes:

  • Token expired
  • Missing permissions
  • Wrong scope

Solutions:

  1. Sign out and sign in again
  2. Check API permissions in Entra
  3. Verify your API scope (e.g., api://your-api-id) is included in ENTRA_SCOPES

Configuration Issues​

Component Not Rendering​

Symptom: Component added to config doesn't appear.

Checklist:

  • Component registered in ComponentRegistry
  • Component name matches exactly (case-sensitive)
  • showWhen condition returns true
  • Check browser console for errors
// Verify registration
import { ComponentRegistry } from '@enterpriseaigroup/client';
console.log(ComponentRegistry.has('MyComponent'));

Store Not Updating​

Symptom: setStore called but UI doesn't update.

Causes:

  • Wrong store path
  • Component not subscribed
  • State mutation instead of replacement

Solutions:

  1. Verify path matches config: useStoreValue('slice.path')
  2. Check path in Redux DevTools
  3. Ensure using setStore correctly: 
    // Correct
    setStore('user.name', 'John', 'MyComponent');

    // Wrong - mutating object directly
    const user = useStoreValue('user');
    user.name = 'John'; // This won't trigger re-render

Tenant Not Loading​

Symptom: Wrong tenant or default tenant loads.

Checklist:

  • Config registered in src/eai.config/index.ts
  • Tenant ID matches URL: ?tenant=my-tenant
  • No typos in tenant ID

Type Errors​

"Type 'X' is not assignable to type 'Y'"​

Symptom: TypeScript errors in tenant config.

Solution: Check src/eai.config/types.ts for correct types:

// Correct component config
{
  component: 'Header',  // string
  priority: 1,          // number
  props: {},            // object
  storeBindings: [],    // array
  showWhen: (state) => boolean,  // function
}

Missing Type Definitions​

Solution:

# Regenerate types
npm run build

# Or restart TypeScript server in VS Code
# Cmd/Ctrl + Shift + P → "TypeScript: Restart TS Server"

Build Issues​

Build Fails with Type Errors​

Solution:

# Check for errors
npm run lint

# Build with verbose output
npm run build 2>&1 | tee build.log

"Out of memory" During Build​

Solution:

# Increase Node.js memory
NODE_OPTIONS="--max-old-space-size=4096" npm run build

API Issues​

CORS Errors​

This shouldn't happen - The BFF proxy handles all API calls.

If you see CORS errors:

  1. You're calling the backend API directly from browser
  2. Use /api/eai/* proxy routes instead: 
    // Wrong - direct call
    fetch('https://api.example.com/endpoint');

    // Correct - via proxy
    fetch('/api/eai/v3/endpoint', { credentials: 'include' });

"Failed to fetch" Errors​

Causes:

  • Network issue
  • Backend down
  • Proxy misconfigured

Solutions:

  1. Check network connectivity
  2. Verify BASE_URL_PUBLIC_API is correct
  3. Check server logs for errors

Performance Issues​

Slow Initial Load​

Causes:

  • Large bundle size
  • Too many components

Solutions:

  1. Use dynamic imports: 
    const HeavyComponent = dynamic(() => import('./HeavyComponent'));
  2. Check bundle with: 
    npm run build && npm run analyze

Store Re-renders​

Symptom: Components re-render too often.

Solution: Use selective selectors:

// Instead of
const fullState = useGlobalSelector((state) => state);

// Use specific paths
const userName = useStoreValue('user.name');

Getting Help​

Debugging Tips​

  1. Check browser console for JavaScript errors
  2. Use Redux DevTools to inspect store state
  3. Check Network tab for API call failures
  4. Read server logs for backend errors

Collecting Information​

When asking for help, include:

  1. What you're trying to do
  2. What you expected to happen
  3. What actually happened
  4. Error messages (full text)
  5. Relevant code snippets
  6. Steps to reproduce

Resources​