Getting startedHow it worksWhat worksConfigurationExamplesTroubleshooting

Troubleshooting

Common issues and how to fix them. This page will grow as we hear from users.

No PR found

If PR mode can't find an existing pull request, you can still continue. DemoTape treats PR mode as a convenience layer, not a hard requirement.

  • Check your branch. Make sure you're on the branch you intend to share.
  • Check GitHub CLI. PR detection uses gh pr view when available.
  • Continue anyway. Even without a detected PR, DemoTape can still create a live share and record reviewer sessions.

Dev server won't start automatically

If PR mode can't figure out how to start your app, specify it directly:

demotape --cmd "npm run dev"
demotape --cmd "pnpm dev" --port 3000

Once a startup command works, DemoTape saves it for that directory and reuses it on later runs.

App loads but API calls fail

Your frontend is being served through the tunnel, but API requests are still going to localhost.

  • Check your API base URL. If your frontend hardcodes http://localhost:8001, DemoTape will try to rewrite it — but if it's in a compiled/bundled file, the rewrite may not catch it.
  • Use relative URLs. Instead of http://localhost:8001/api/users, use /api/users. Relative URLs route through the tunnel automatically.
  • Check that your API port is detected. Run demotape doctor to see which ports DemoTape found.

“Not logged in” error

Your token may have expired (tokens last 30 days). Run:

demotape login

Wrong port detected

If DemoTape picks the wrong port, specify it directly:

demotape --port 3000

You can also run demotape doctor to see the full detection output with scores for each port.

“App is still starting” page

If your reviewer sees this, your dev server hasn't finished starting. DemoTape shows a holding page until the upstream port responds. Wait for your dev server to be ready, then refresh.

Session not recording

  • Check that recording is enabled. If you passed --no-record, sessions won't be recorded.
  • Check the content type. Recording is only injected into text/html responses. If your app serves HTML with a different content type, the recorder won't load.
  • Check for CSP headers. If your app sets a strict Content Security Policy that blocks inline scripts, the recorder script may be blocked. Check the browser console for CSP violations.

Cookies not working

DemoTape rewrites Set-Cookie domain attributes from localhost to the public URL. To verify cookies work, try the cookie-session example. If cookies still don't work:

  • Check if your app sets cookies with an explicit non-localhost domain
  • Check if SameSite=Strict is blocking cross-origin cookie flow
  • Try --no-rewrite-cookies to disable rewriting and debug manually

WebSocket connection fails

WebSocket connections are proxied by default. If they're not working:

  • Make sure your WebSocket URL uses localhost or 127.0.0.1 — DemoTape only rewrites these origins
  • Check if the port is detected — run demotape doctor
  • Try --debug to see proxy logs for WebSocket upgrade attempts

Tunnel won't connect

  • Check your network. The tunnel needs outbound HTTPS access.
  • Corporate firewall? Some firewalls block non-standard outbound connections. Check with your IT team.
  • Try again. Transient network issues can cause connection failures. The CLI will show the last few lines of tunnel output.

Debug mode

For detailed proxy and tunnel logs:

demotape --debug

For recording-specific logs:

demotape --debug-recording

For port detection diagnostics:

demotape doctor

Try an example first

If something isn't working, try one of the examples to narrow down whether the issue is with your app or with DemoTape. The debugging-failures example is designed to reproduce common failure modes.

Still stuck?

Reach out at [email protected] and we'll help you sort it out.