FAQ & Troubleshooting

Common Issues

Module shows "Waiting for auth" indefinitely

Cause: The Shell is not sending the AUTH_SESSION message, or the module can't receive it.

Fix:

1. Make sure the module URL is correct in the Shell's module settings
2. Check that ShellAuthProvider is wrapping your app in layout.tsx
3. Verify the module is running on the expected port
4. Open browser DevTools → Console and look for [ShellAuth] messages
5. Check that window.parent !== window (module must be in an iframe)

Module doesn't load in iframe

Cause: CSP or X-Frame-Options headers blocking iframe embedding.

Fix: Ensure next.config.ts includes:

async headers() {
  return [{
    source: '/(.*)',
    headers: [
      { key: 'X-Frame-Options', value: 'ALLOWALL' },
      { key: 'Content-Security-Policy',
        value: "frame-ancestors 'self' https://*.insolitum.ai http://localhost:*" },
    ],
  }];
}

Data queries return empty results

Cause: Missing organization_id filter or incorrect RLS policy.

Fix:

1. Use useModuleApi() instead of raw Supabase client — it auto-filters
2. Verify the table has organization_id column
3. Check RLS policy allows the current user
4. Confirm organizationId is not null in useShellAuth()

NATS events not arriving

Cause: WebSocket connection not established or wrong channel.

Fix:

1. Check connected state from useNats() — is it true?
2. Verify NEXT_PUBLIC_WS_URL environment variable
3. Check browser DevTools → Network → WS tab for Socket.io connection
4. Ensure the gateway is running (ws://localhost:4200 for dev)
5. Verify you're subscribing to the correct channel

Module Validator shows CORS errors

Cause: Browser security prevents cross-origin requests from the validator.

Fix: This is expected for some checks (iframe, security headers). The full validation runs server-side during the actual marketplace review. The browser-based validator can still check:

• Module ID format
• HTTPS
• Health endpoint (if CORS allows)
• Performance (via no-cors mode)

Build fails with TypeScript errors

Fix:

# Check for type errors
pnpm typecheck
 
# Common fix: update tsconfig paths
{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

Module not appearing in marketplace after approval

Cause: Module status might not have been updated, or the subscription is not active.

Fix:

1. Check module status in Partner Panel — should be published
2. Verify the deploy_url is accessible
3. Check health endpoint is responding
4. Contact Insolitum support if the issue persists

Frequently Asked Questions

Can I use a different framework than Next.js?

Technically, any web application that:

• Serves over HTTPS
• Has a /api/health endpoint returning { status: "ok" }
• Allows iframe embedding (CSP headers)
• Implements the postMessage auth protocol

can work as a module. However, the module-starter template and all tooling are built for Next.js 14, so we strongly recommend it.

How do I debug inside an iframe?

1. Open browser DevTools (F12)
2. Use the frame selector dropdown in the Console tab
3. Select your module's iframe to execute console commands in its context
4. Use the Network tab to see requests from both Shell and module

Can I access data from other modules?

Modules share the Supabase database, so if your module has the correct table access and RLS policies, you can query other modules' tables. However, this creates tight coupling and is not recommended. Use NATS events for module-to-module communication instead.

What's the maximum module size?

There's no hard limit, but:

• Page load time must be under 5 seconds
• Health endpoint must respond within 5 seconds
• Use output: 'standalone' to minimize bundle size

How do I handle module versioning?

1. Update NEXT_PUBLIC_MODULE_VERSION in your environment
2. Update the version in your health endpoint response
3. Add a changelog entry when submitting an update to the marketplace
4. The marketplace supports version history via the changelog field

Where do I get help?

• Documentation: You're reading it
• Module Validator: /tools/validator
• Code Examples: /tools/playground
• Support: partners@insolitum.ai
• GitHub Issues: Report bugs at the Insolitum Universe repository