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

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

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

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 aren’t working

The commands like /data-apps-builder:create-app require the Wallabi plugin to be configured. Re-run pnpm run setup if they’re not available.

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.

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.