Troubleshooting

Common issues and solutions when working with PancakeJS.

Build Issues

"Cannot find module" Errors

Problem: TypeScript can't find workspace packages.

Solution: Ensure you've built the packages:

pnpm install
pnpm build

Widget Build Fails

Problem: Vite can't build widget files.

Solution:

1. Check that widget entry paths are correct:

ui: {
  entry: 'src/widgets/my-widget.tsx', // Relative to project root
}

2. Ensure React is installed:

pnpm add react react-dom

Runtime Issues

"useUniversalApp must be used within a UniversalAppProvider"

Problem: Hook used outside provider context.

Solution: Wrap your widget with the provider:

function App() {
  return (
    <UniversalAppProvider>
      <MyWidget />
    </UniversalAppProvider>
  );
}

"Invocation not available - adapter not initialized"

Problem: Trying to access invocation data before adapter initializes.

Solution: Use the fallback prop:

<UniversalAppProvider fallback={<Loading />}>
  <MyWidget />
</UniversalAppProvider>

Widget Shows Blank

Problem: Widget HTML loads but nothing renders.

Solution:

1. Check browser console for errors
2. Ensure #root element exists in HTML
3. Verify React mounting code:

createRoot(document.getElementById('root')!).render(<App />);

Communication Issues

postMessage Not Received

Problem: MCP Apps adapter can't communicate with host.

Solutions:

• Check iframe is loaded from correct origin
• Verify CSP allows the host origin
• Check browser console for blocked messages

window.openai is undefined

Problem: ChatGPT Apps adapter can't find the API.

Solutions:

• Ensure widget is running in ChatGPT environment
• Check if ChatGPT SDK is loaded before your widget
• Use the inspector's ChatGPT harness for testing

Tool Calls Timeout

Problem: callTool never resolves.

Solutions:

1. Check server is running and reachable
2. Verify tool name matches server registration
3. Check network tab for failed requests
4. Increase timeout if needed:

createMcpAppsUiAdapter({ timeout: 60000 }); // 60 seconds

State Issues

State Not Persisting

Problem: useWidgetState loses data on refresh.

Solutions:

1. Check if host supports persistent state:

const host = useHost();
console.log('Persistent state:', host.capabilities.persistentState);

2. In development, state uses in-memory storage by default

State Type Errors

Problem: TypeScript errors with state values.

Solution: Provide explicit types:

const [items, setItems] = useWidgetState<Item[]>('items', []);

CSP Issues

"Refused to connect"

Problem: API calls blocked by CSP.

Solution: Add domain to CSP config:

ui: {
  csp: {
    connectDomains: ['api.example.com'],
  },
}

"Refused to load the image"

Problem: Images blocked by CSP.

Solution: Add image domains:

ui: {
  csp: {
    imgDomains: ['images.example.com'],
  },
}

Development Tips

Enable Debug Mode

createMcpAppsUiAdapter({ debug: true });

createChatGptUiAdapter({ debug: true });

Use the Inspector

1. Start dev server: pnpm universal-apps dev
2. Open: http://localhost:3000/_inspector
3. Test tools and widgets in both harnesses

Check Adapter Detection

import { detectAdapterType } from '@pancakeapps/react';

console.log('Detected adapter:', detectAdapterType());

Strict Mode for Development

Catch issues early:

<UniversalAppProvider strict={process.env.NODE_ENV === 'development'}>
  <MyWidget />
</UniversalAppProvider>

Cloudflare Deployment Issues

"Worker exceeded CPU time limit"

Problem: Worker is taking too long to execute.

Solution:

• Optimize heavy computations
• Use streaming for large responses
• Consider using Durable Objects for stateful operations

"Script startup exceeded CPU time limit"

Problem: Too much code running at startup.

Solution:

• Lazy-load heavy dependencies
• Reduce bundle size
• Use dynamic imports

"Memory limit exceeded"

Problem: Worker using too much memory.

Solution:

• Stream large payloads instead of loading into memory
• Avoid large arrays/objects
• Use external storage (KV, R2) for large data

Getting Help

1. Check the examples for working patterns
2. Review test files in the repo for usage patterns
3. Open an issue on GitHub with:
   • Node.js version
   • Package versions
   • Minimal reproduction
   • Error messages and stack traces

Common Error Messages