Troubleshooting

Common issues and solutions when building with Pancake.

Installation Issues

"Cannot find module '@pancake-apps/server'"

Problem: Package not installed or TypeScript can't resolve it.

Solution:

# Install packages
pnpm add @pancake-apps/server @pancake-apps/web

# Check package.json has the dependency
cat package.json | grep pancake

TypeScript Errors with Zod

Problem: Type errors when using Zod schemas.

Solution: Make sure you have compatible Zod version:

pnpm add zod@^3.24.0

Build Issues

"Module not found" During Build

Problem: Build fails with missing module errors.

Solution:

1. Clear node_modules and reinstall:

rm -rf node_modules pnpm-lock.yaml
pnpm install

2. Ensure all dependencies are in dependencies, not just devDependencies

Vite Build Fails

Problem: React views fail to build.

Solution:

1. Check React is installed:

pnpm add react react-dom
pnpm add -D @types/react @types/react-dom

2. Verify vite.config.ts:

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';

export default defineConfig({
  plugins: [react()],
});

Runtime Issues

"PancakeProvider not found"

Problem: React hooks used outside provider.

Solution: Wrap your app with PancakeProvider:

import { PancakeProvider } from '@pancake-apps/web';

function App() {
  return (
    <PancakeProvider>
      <YourView />
    </PancakeProvider>
  );
}

View Shows Blank Page

Problem: View loads but nothing renders.

Solutions:

1. Check browser console for errors

2. Verify root element exists in HTML:

<div id="root"></div>

3. Check React mount code:

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

Data Not Loading

Problem: useViewParams returns undefined data.

Solutions:

1. Check handler is returning data:

handler: async ({ userId }) => {
  const data = await fetchData(userId);
  console.log('Handler returning:', data);  // Debug
  return data;
},

2. Verify data schema matches handler output

Tunnel Issues

"cloudflared not found"

Problem: Cloudflare tunnel can't start.

Solution: Install cloudflared:

brew install cloudflared

curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64.deb -o cloudflared.deb
sudo dpkg -i cloudflared.deb

winget install Cloudflare.cloudflared

"ngrok not found"

Problem: ngrok tunnel can't start.

Solution: Install ngrok:

# macOS
brew install ngrok

# Other platforms: https://ngrok.com/download

Tunnel URL Changes Every Restart

Problem: Development URL keeps changing.

Solution: This is expected for free tunnels. For stable URLs:

• Cloudflare: Create a named tunnel (requires account)
• ngrok: Use a paid plan with reserved domains

Port Issues

"Port 3000 already in use"

Problem: Another process is using the port.

Solutions:

1. Find and kill the process:

lsof -i :3000
kill -9 <PID>

2. Use a different port:

SERVER_PORT=4000 pnpm dev

3. The dev script auto-finds available ports, check terminal output

Claude Desktop Issues

Tools Not Showing Up

Problem: Claude doesn't see your tools.

Solutions:

1. Verify config file location:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Check JSON syntax:

{
  "mcpServers": {
    "my-app": {
      "url": "https://your-tunnel-url.trycloudflare.com/mcp"
    }
  }
}

3. Restart Claude Desktop after config changes

4. Verify the MCP endpoint is accessible:

curl -X POST https://your-tunnel-url/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

"Connection refused" in Claude

Problem: Claude can't connect to your server.

Solutions:

1. Check server is running
2. Verify tunnel is active
3. Test URL in browser first
4. Check firewall settings

ChatGPT Issues

Action Not Working

Problem: ChatGPT can't call your tools.

Solutions:

1. Verify OpenAPI spec is accessible:

curl https://your-url/openapi.json

2. Check plugin manifest:

curl https://your-url/.well-known/openai-plugin.json

3. Re-import the action in your Custom GPT

Debug Mode

Enable debug logging for more information:

const app = createApp({
  name: 'my-app',
  version: '0.1.0',
  config: {
    debug: true,
  },
});

This logs:

• Incoming requests
• Tool invocations
• Protocol detection
• Errors with stack traces

Common Error Messages

Getting More Help

1. Check the examples for working patterns
2. Enable debug mode and check logs
3. Test endpoints with curl before connecting AI clients
4. Open an issue on GitHub with:
   • Node.js version
   • Package versions
   • Minimal reproduction steps
   • Full error message and stack trace

Next Steps

• Examples: Working code to reference
• API Reference: Complete API documentation
• Local Development: Development setup