Troubleshooting Common Issues

Solutions to common problems encountered when developing widgets on the INVENT platform.

---

Table of Contents

1. Development Environment
2. Widget Creation
3. Local Development
4. Module Federation
5. API Integration
6. Authentication
7. Deployment
8. Performance

---

Development Environment

NPM Install Fails

Problem: npm install fails with authentication error

Solution:

1. Verify NPM token is configured:

   cat ~/.npmrc

2. Ensure token has read_api access
3. Check token hasn't expired in GitLab
4. Reconfigure if needed:

   npm config set --location=user @invent:registry=https://gitlab.apptrium.io/api/v4/packages/npm/
   npm config set --location=user //gitlab.apptrium.io/api/v4/packages/npm/:_authToken=YOUR_TOKEN

See: Prerequisites → NPM Configuration

---

Node Version Mismatch

Problem: Build fails with Node.js version error

Solution:

1. Check required Node version:

   node --version

2. Install Node 20 (LTS):

   # macOS
   brew install node@20
   
   # Or use nvm
   nvm install 20
   nvm use 20

3. Verify version:

   node --version  # Should show v20.x.x

---

Widget Creation

Port Already in Use

Problem: npm run dev fails - port already in use

Solution:

1. Find process using the port:

   lsof -i :5XXX  # Replace XXX with your port number

2. Kill the process:

   kill -9 <PID>

3. Or use a different port temporarily by modifying package.json

Note: Widget ports follow format 5{GitLab Project ID} - don't change permanently

---

Widget Config Validation Fails

Problem: widget-config.json has validation errors

Common Issues:

• Port doesn't match GitLab Project ID
• widgetType is not 0, 1, or 2
• Missing required fields

Solution:

1. Verify port = 5{GitLab Project ID}
2. Check widgetType enum:
   • 0 = Platform widget
   • 1 = Dashboard widget (most common)
   • 2 = Universal widget
3. Validate JSON syntax:

   cat widget-config.json | python -m json.tool

See: Widget Config

---

Local Development

Widget Not Loading in Browser

Problem: npm run dev succeeds but widget doesn't load

Checklist:

1. Verify dev server is running:

   # Should see "Compiled successfully"

2. Check correct port in browser URL:

   http://localhost:5XXX  # XXX = your project ID

3. Clear browser cache (Cmd+Shift+R / Ctrl+Shift+R)
4. Check browser console for errors
5. Verify src/main.tsx exists and is correct

---

Hot Module Replacement Not Working

Problem: Changes don't reflect without full reload

Solution:

1. Ensure webpack dev server is running (npm run dev or npm run start_federation)
2. Check no syntax errors in console
3. Try restarting dev server
4. For styled-components changes, full reload may be needed

---

Cannot Connect to Portal

Problem: Local widget doesn't load in portal when using dev-version

Solution:

1. Verify widget is set to dev-version in ICP:

   • Open ICP → Micro Apps Versioning
   • Find your widget
   • Click cog icon → Select "dev-version"
   • Click Apply

2. Ensure npm run start_federation is running (not npm run dev)

3. Check CORS/network errors in browser console

4. Verify you're running on correct port (5[Project ID])

See: Development Workflow → Connecting to Portal

---

Module Federation

Shared Dependency Version Conflict

Problem: Widget fails to load - shared dependency version mismatch

Error Example:

Shared module is not available for eager consumption

Solution:

1. Check @invent/webpack-config version
2. Update to match host application:

   npm update @invent/webpack-config

3. Ensure React version matches platform:

   {
     "react": "^18.0.0",
     "react-dom": "^18.0.0"
   }

4. Clear node_modules and reinstall:

   rm -rf node_modules package-lock.json
   npm install

---

remoteEntry.js Not Found

Problem: Widget fails to load - 404 on remoteEntry.js

Solution:

1. Verify widget is deployed to Widget Store
2. Check widget version in ICP matches deployed version
3. Clear browser cache
4. For local development, ensure npm run start_federation is running

---

API Integration

httpClient Returns 401 Unauthorized

Problem: API calls fail with authentication error

Checklist:

1. User is logged in to portal
2. JWT token is valid (not expired)
3. API endpoint requires authentication
4. User has correct permissions

For OAuth APIs:

1. Verify ProxyApp is configured correctly
2. Check user has completed OAuth flow
3. Ensure token refresh is working

See: API Integration

---

CORS Error

Problem: API call blocked by CORS policy

Solution:

1. Not a Widget Issue - CORS must be configured on API server
2. Use httpClient (includes proxy through BfF)
3. Contact backend team to configure CORS headers
4. For local development, use BfF proxy

---

Authentication

ProxyLogin Not Showing

Problem: ProxyLogin component doesn't render

Checklist:

1. ProxyApp wraps your component
2. Provider name matches configuration
3. authUrl is correct
4. User hasn't completed OAuth already

See: ProxyLogin Tutorial

---

OAuth Token Expired

Problem: API calls fail after some time

Solution:

1. Implement token refresh in ProxyApp
2. Use useAuth hook to check auth status
3. Handle refresh token logic
4. Show re-auth UI when needed

---

Deployment

Semantic Release Not Triggering

Problem: Merge request merged but no version released

Checklist:

1. MR title has semantic prefix: feat:, fix:, docs:, etc.
2. Merged to master/main branch
3. CI pipeline completed successfully
4. Check GitLab CI/CD logs for errors

See: Semantic Release

---

Widget Not Appearing in Portal

Problem: Widget deployed but doesn't show in Micro App Library

Solution:

1. Verify first release completed:

   • Check GitLab tags for version tag
   • Check Widget Store has widget entry

2. Contact INVENT technical manager to:

   • Register widget in portal
   • Configure widget metadata
   • Add widget to portal's widget list

3. Check context rules in widget-config.json:

   • May be filtered by current dashboard context
   • Verify contextRules configuration

See: Widget Publishing

---

Pipeline Fails on Build

Problem: GitLab CI pipeline fails during build step

Common Causes:

1. Linting Errors - Run npm run lint locally
2. Test Failures - Run npm test locally
3. Type Errors - Run npm run build locally
4. Missing Dependencies - Check package.json

Solution:

1. Fix errors locally first
2. Ensure all tests pass
3. Commit fixes and push again

---

Performance

Widget Loads Slowly

Problem: Widget takes long time to load

Solutions:

1. Reduce Bundle Size

   npm run analyze

   • Remove unused dependencies
   • Use code splitting for large components
   • Lazy load heavy features

2. Optimize Images

   • Use SVG for icons
   • Compress images
   • Lazy load images

3. Minimize Re-renders

   • Use React.memo for expensive components
   • Optimize useEffect dependencies
   • Use useMemo for expensive calculations

See: Module Federation → Best Practices

---

Memory Leak

Problem: Browser memory usage increases over time

Common Causes:

1. Event Listeners Not Cleaned Up

   useEffect(() => {
     const handler = () => {};
     window.addEventListener("event", handler);
   
     // Must return cleanup!
     return () => window.removeEventListener("event", handler);
   }, []);

2. WebSocket Not Unsubscribed

   useEffect(() => {
     const wsExt = getExtension("@invent/bff-ws-ext");
     wsExt.subscribe("Event", "subscription-id", handler);
   
     // Must unsubscribe!
     return () => wsExt.unsubscribe("Event", "subscription-id");
   }, []);

3. State Not Cleaned Up

   • Use useDeleteSharedValue when widget unmounts
   • Clear intervals and timeouts

---

Get Help

• Check GitLab Issues for similar problems
• Review example widgets in the platform
• Contact your INVENT technical manager
• Check platform status page

---

Report an Issue

If you've found a bug or issue not covered here:

1. Check GitLab Issues first
2. Gather error details:
   • Error messages (full stack trace)
   • Steps to reproduce
   • Expected vs actual behavior
   • Environment details (Node version, OS, etc.)
3. Create issue in appropriate repository