How to Debug ChatGPT Apps: Troubleshooting Guide for MCP App Development

[Updated 2026-02-05] Debugging ChatGPT Apps is frustrating without the right tools. Your app works in development but breaks in ChatGPT. Errors appear with no stack trace. Display modes behave differently than expected.

TL;DR: Use sunpeak’s local simulator (sunpeak dev) with browser DevTools for debugging. Create simulation files for deterministic states. Test all display modes with createSimulatorUrl. Check MCP server logs for tool invocation errors.

This guide covers the most common ChatGPT App debugging scenarios and how to fix them.

Setting Up a Debug Environment

The sunpeak ChatGPT App framework provides the debugging infrastructure you need. Start a new project or use an existing one:

pnpm add -g sunpeak && sunpeak new
cd my-app && pnpm dev

Your debug environment includes:

• ChatGPT App Simulator at localhost:6767 with full DevTools access
• MCP Server at localhost:6766 with request logging
• Hot Reloading for instant feedback on code changes
• Simulation Files for testing specific states

Open your browser DevTools (F12) alongside the simulator. You now have full visibility into your app’s behavior.

Debugging ChatGPT App Hooks

The sunpeak ChatGPT App framework provides hooks like useToolData, useDisplayMode, and useTheme. When these return unexpected values, use simulation files to isolate the problem.

Debugging Tool Input

useToolData returns both the tool input (arguments the host passed when invoking your tool) and the tool output (structured content from your MCP server). The sunpeak simulator displays live runtime values in the sidebar, including the current toolInput. You can modify these values directly in the sidebar to test different inputs without restarting your app.

For persistent test cases or automated testing, create a simulation file:

{
  "tool": {
    "name": "my_tool",
    "inputSchema": {
      "type": "object",
      "properties": {
        "query": { "type": "string" }
      }
    }
  },
  "toolInput": {
    "arguments": { "query": "test search" }
  }
}

Now useToolData() returns { input: { query: "test search" }, ... } consistently.

Debugging Tool Output

useToolData also provides the tool output — the structuredContent from your MCP server. Like tool input, the simulator sidebar shows the current tool data values and lets you modify them on the fly.

For debugging your ChatGPT App when running remotely in ChatGPT (where you don’t have access to the simulator sidebar), add console logging:

import { useToolData } from 'sunpeak';

export function MyResource() {
  const { output } = useToolData();

  // Helpful for debugging in production ChatGPT
  console.log('Tool data:', JSON.stringify(output, null, 2));

  if (!output) {
    return <div>Loading...</div>;
  }

  return <div>{output.title}</div>;
}

Add toolResult to your simulation file:

{
  "toolResult": {
    "content": [{ "type": "text", "text": "Success" }],
    "structuredContent": {
      "title": "Debug Test",
      "items": [1, 2, 3]
    }
  }
}

Debugging Display Mode Issues

ChatGPT Apps render in three display modes with different constraints:

• inline — Embedded in the chat flow.
• pip — Floating picture-in-picture window.
• fullscreen — Modal overlay covering the full viewport.

Use useDisplayMode to debug mode-specific issues:

import { useDisplayMode } from 'sunpeak';

export function MyResource() {
  const displayMode = useDisplayMode();

  console.log('Current display mode:', displayMode);

  return (
    <div className={displayMode === 'fullscreen' ? 'p-8' : 'p-2'}>
      {/* Adapt layout to mode */}
    </div>
  );
}

Test all modes systematically using createSimulatorUrl:

import { createSimulatorUrl } from 'sunpeak';

// Test inline mode
const inlineUrl = createSimulatorUrl({
  simulation: 'my-resource',
  displayMode: 'inline',
});

// Test fullscreen mode
const fullscreenUrl = createSimulatorUrl({
  simulation: 'my-resource',
  displayMode: 'fullscreen',
});

Common Errors and Fixes

Blank Screen / White Screen of Death

Symptom: Your app shows nothing, no errors visible.

Debug steps:

1. Open DevTools Console, look for JavaScript errors
2. Check if useToolData() returns undefined output initially
3. Add error boundaries and loading states:

export function MyResource() {
  const { output } = useToolData();

  if (!output) {
    return <div className="p-4">Loading...</div>;
  }

  try {
    return <div>{output.data.map(/* ... */)}</div>;
  } catch (error) {
    console.error('Render error:', error);
    return <div className="p-4 text-red-500">Something went wrong</div>;
  }
}

MCP Server Connection Failed

Symptom: App won’t load, connection errors in console.

Debug steps:

1. Verify MCP server is running (pnpm dev shows no errors)
2. Check ngrok tunnel is active and URL is correct
3. Verify ChatGPT settings have the full URL with /mcp path
4. Look for CORS errors in DevTools Network tab

# Terminal 1: Start sunpeak
pnpm dev

# Terminal 2: Start tunnel
ngrok http 6766

# Use the ngrok URL + /mcp in ChatGPT settings
# Example: https://abc123.ngrok.io/mcp

ChatGPT Shows Old Version of Your App

Symptom: You’ve made changes to your app, but ChatGPT keeps showing the old version.

Cause: ChatGPT aggressively caches your app’s resources and tool definitions.

Fix: Clear the cache completely:

1. Go to ChatGPT Settings → Apps and find your app
2. Click Refresh to force ChatGPT to re-fetch your tool definitions
3. Start a new chat before calling your app again—existing chats may have cached tool schemas
4. If still seeing old behavior, remove and re-add the app in settings

This cache invalidation is especially important after changing tool names, input schemas, or the MCP server URL.

Theme Not Applying

Symptom: App looks wrong in dark/light mode.

Fix: Use the useTheme hook and test both themes:

import { useTheme } from 'sunpeak';

export function MyResource() {
  const theme = useTheme();

  return (
    <div className={theme === 'dark' ? 'bg-gray-900 text-white' : 'bg-white text-gray-900'}>
      {/* Theme-aware content */}
    </div>
  );
}

Test both themes in the simulator:

createSimulatorUrl({ simulation: 'my-resource', theme: 'dark' });
createSimulatorUrl({ simulation: 'my-resource', theme: 'light' });

Debugging MCP Server Requests

The MCP server logs all requests to your terminal. Watch for:

# Successful tool call
[MCP] Tool call: show_resource { query: "test" }
[MCP] Response: 200 OK

# Failed tool call
[MCP] Tool call: show_resource { query: "test" }
[MCP] Error: Cannot read property 'map' of undefined

Debugging Tips

Use the simulator sidebar. The sunpeak simulator displays all runtime values (toolInput, toolOutput, displayMode, theme) in the sidebar. Edit them live to test different states without restarting.

Use simulation files for reproducibility. Create files for each state you need to test: loading, error, empty data, full data, edge cases. These are especially useful for automated testing.

Use the browser console in ChatGPT. In ChatGPT, you can see your ChatGPT App state by opening the browser console and switching the JS context selector dropdown from top to root (there may be multiple if you’ve called your app multiple times in the conversation).

Add logging for remote debugging. Console logs are your primary debugging tool when your ChatGPT App runs in real ChatGPT. The simulator sidebar isn’t available there, so add strategic console.log statements for production debugging.

Test display modes early. Layout bugs in inline mode are easier to fix before you’ve built complex UIs.

Check the browser Network tab. MCP communication issues often show up as failed requests or unexpected payloads.

Use React DevTools. The React DevTools extension shows component hierarchy and prop values in real-time.

Next Steps

Debugging is faster with the right infrastructure. Sunpeak provides the ChatGPT App simulator, logging, and testing tools you need to catch issues before they reach ChatGPT.

Get started:

pnpm add -g sunpeak && sunpeak new

• Read the testing guide for automated debugging
• Learn about the ChatGPT App framework
• Check the sunpeak documentation for API references
• Star sunpeak on GitHub