Skip to content

Troubleshooting

Jump to bottom
Dipkumar Patel edited this page Feb 4, 2026 · 1 revision

Troubleshooting

Installation Issues

pip install fails with dependency conflicts

Try installing in a fresh virtual environment:

python -m venv .venv
source .venv/bin/activate  # Linux/macOS
# or .venv\Scripts\activate on Windows
pip install -e ".[google]"

paperbanana: command not found

The CLI entry point wasn't installed. Verify you used pip install -e ".[google]" (not just pip install). If using a virtual environment, make sure it's activated.

API Key Issues

GOOGLE_API_KEY not set error

The key needs to be available as an environment variable. Check:

  1. .env file exists in the project root with GOOGLE_API_KEY=your-key
  2. Or export it directly: export GOOGLE_API_KEY=your-key
  3. Or pass it in the MCP config's env block

403 Forbidden or API key not valid

  • Verify the key at Google AI Studio
  • Ensure the Gemini API is enabled for your Google Cloud project
  • Free tier keys have rate limits. If you're hitting them, wait a few minutes and retry.

Rate limit errors

Gemini's free tier has per-minute and per-day limits. Each diagram generation makes multiple API calls (planning, styling, 3x visualizer, 3x critic). If you're generating many diagrams in sequence, add delays between runs or use a paid API key.

Generation Issues

Output is blank or mostly white

This occasionally happens with Gemini's image generation. Re-run the same command. The non-deterministic nature of generation means a second attempt often succeeds.

Diagram doesn't match the methodology text

This is usually a retrieval or planning issue. Try:

  1. Making the methodology text more detailed and explicit
  2. Increasing num_retrieval_examples in config to give the Planner more reference context
  3. Adjusting the caption to be more specific about what the diagram should emphasize

Labels are cut off or overlapping

The Critic should catch this across iterations, but if it persists after 3 rounds, the description may be overloading the Visualizer. Simplify the methodology text or break a complex system into sub-diagrams.

paperbanana plot generates incorrect code

The plot pipeline generates Matplotlib code via Gemini. If the generated code has errors:

  1. Check outputs/run_<timestamp>/ for the generated .py file
  2. Review and manually correct the code
  3. Report the issue with the data file and intent string so we can improve the prompts

MCP Server Issues

Server not appearing in IDE

  • Verify the cwd path in your MCP config points to the PaperBanana installation root
  • Check that python -m mcp_server works when run manually from the project directory
  • Restart your IDE after modifying MCP configuration

Timeout during generation

Diagram generation takes 30-90 seconds. If your MCP client has a timeout shorter than this, you'll need to increase it. Check your client's documentation for timeout configuration.

Still stuck?

Open a Discussion with the error output, your environment details, and what you've already tried.

Clone this wiki locally