Skip to content

Troubleshooting

This page covers common issues you might run into and how to fix them. When in doubt, the fastest path is often to describe the problem to Claude Code — it has context on the codebase and common patterns, and can usually diagnose the issue.

Most users develop inside an Edit Session — the issues there look different from running an app host on your own machine. The first section covers Edit Sessions; the Local Setup section below is for the advanced path.

Edit Session Issues

Section titled “Edit Session Issues”

Your session won’t start or is stuck provisioning

  • Provisioning usually takes a minute or two. If it’s been longer, refresh the Wallabi app and check the session status. If it shows an error, end the session and start a new one.
  • If new sessions consistently fail to start, reach out to your Wallabi contact.

You can’t open your apps from the session

  • Check that the dev server is running in the terminal panel. If it’s stopped, restart it with pnpm run dev.
  • Open your apps from the Wallabi app rather than from URLs in the terminal — the Wallabi app routes you through your active session.

Your session feels frozen or unresponsive

  • Refresh the browser tab. Your work is preserved.
  • If that doesn’t help, end the session from the Wallabi app and start a new one — your committed work is in Git and your in-progress changes are usually safe.

Claude Code isn’t responding in your session

  • Check that you’re typing into the Claude Code terminal panel, not the dev server terminal.
  • Restart Claude Code: in its terminal, press Ctrl+C and run claude again. It’s already signed in for you.

Claude Code Issues

Section titled “Claude Code Issues”

Claude Code asks to “trust this folder”

  • The first time you open Claude Code in your app host directory, it will ask if you trust the folder. This is a safety prompt — select Yes to continue. You only need to do this once per project.

Claude Code keeps asking for permission to run commands

  • Claude Code will regularly ask things like “Can I run pnpm run build?” or “Can I edit this file?” before taking actions. This is normal — it’s confirming before making changes. You can approve each one individually, or select the option to allow similar actions automatically for the session.

Claude Code can’t see your data

  1. Make sure the dev server is running — Claude Code connects through it
  2. Try restarting your Claude Code session
  3. If you’re working locally, check that your .env.local file exists and has valid values

Slash commands like /begin aren’t working

  • These commands come from the data-apps-builder plugin. In Edit Sessions, the plugin is pre-installed — try restarting Claude Code first.
  • If you’re working locally and the plugin isn’t installed:
    1. In Claude Code, open the plugin marketplace
    2. Search for wallabi-plugins
    3. Install the data-apps-builder plugin
    4. Restart your Claude Code session

What should happen in my app when I’m talking to Claude Code?

  • As you describe changes to Claude Code, it edits your app’s code. The dev server picks up those changes and your browser reloads automatically. You should see your app update in the browser within a few seconds of Claude Code making changes. If nothing changes, check that your dev server is still running.

Data and App Issues

Section titled “Data and App Issues”

An app is showing wrong or unexpected data

  • Ask Claude Code to investigate — describe what you’re seeing vs. what you expected. It can examine the underlying queries and trace the issue.
  • Check that you’re looking at the right data source in the Wallabi app.

Apps load but show no data

  • Check that the data source is connected in the Wallabi app.
  • Open your browser’s developer console (usually F12 or Cmd+Option+I) and look for error messages — authentication errors (401, 403) usually mean your API token needs updating (local setup only — Edit Sessions handle this for you).

Filters aren’t working

  • Filters are handled automatically by the platform. If they’re not applying, ask Claude Code to check the filter configuration in your app.

Dev Console Errors and Warnings

Section titled “Dev Console Errors and Warnings”

Your browser’s developer console (F12 or Cmd+Option+I) may show warnings or errors while your app is running. Here’s how to handle them:

Warnings you can usually ignore

  • Deprecation warnings and minor React warnings are common during development and don’t affect your app’s behavior.

Errors worth investigating

  • Authentication errors (401, 403) — your API token likely needs updating.
  • Network errors or failed data requests — check that your dev server is running and your data source is connected.
  • Rendering errors — these usually mean something in your app’s code needs fixing.

If you’re unsure whether an error matters, copy it and paste it into Claude Code. It can diagnose most issues and suggest a fix.

Local Setup Issues

Section titled “Local Setup Issues”

These apply only if you’re following the Local Setup path on your own machine.

Missing environment variables on startup

  • The setup script creates a .env.local file with your configuration. If it’s missing, re-run pnpm run setup.

Authentication errors (401 responses)

  • Your API token may be expired. Generate a new one in the Wallabi app under Settings > API Tokens, then update your .env.local file.

pnpm install fails

  • Check your Node.js version with node --version — it needs to be v22. Use NVM to switch versions.

Build errors after pulling changes

  • Dependencies may be out of sync. Run pnpm install then pnpm run build.

The dev server won’t start

  • Another program may be using the same port. Check the error message for details.
  • Try running pnpm run build first, then pnpm run dev.

Changes aren’t showing up

  • The dev server reloads automatically, but sometimes a full restart is needed. Stop the server, run pnpm run build, then pnpm run dev.

General Tips

Section titled “General Tips”
  • Ask Claude Code first — describe the error and let it investigate. It has context on the codebase and common patterns.
  • Check the dev server — most issues trace back to the dev server not running or needing a restart.
  • Check the browser console — open your browser’s developer tools (F12 or Cmd+Option+I) to see error messages that aren’t visible on the page.
  • If you’re working locally, rebuild after pulling changes — run pnpm install && pnpm run build after pulling updates from your team.