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.

Setup Issues

Section titled “Setup Issues”

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 (see Getting Started).

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.

Dev Server Issues

Section titled “Dev Server Issues”

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.

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.

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.

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 (pnpm run dev) — Claude Code connects through it
  2. Check that your .env.local file exists and has valid values
  3. Try restarting your Claude Code session

Slash commands like /begin aren’t working

  • The Wallabi commands (/begin, /ship, /create-app, /generate-transform) require the data-apps-builder plugin from the wallabi-plugins marketplace. To install it:
    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
  • If you’ve already installed the plugin, try restarting your Claude Code session. Running pnpm run setup will also configure the plugin automatically.

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 Transform Issues

Section titled “Data and Transform 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.

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.

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.
  • Rebuild after pulling changes — always run pnpm install && pnpm run build after pulling updates from your team.
  • 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.