open/multimodal-rag-guide
1
0
Fork 0
Code Activity Actions
multimodal-rag-guide/troubleshooting.md
Kjell Tore Guttormsen edcd1721df Initial commit: multimodal RAG guide with Claude Code 
Prompt-driven guide for building multimodal search using
Gemini Embedding 2 + Pinecone + Claude Code. Includes example
data (NASA public domain), step-by-step prompts, concepts
explainer, cost breakdown, and troubleshooting guide.
2026-03-12 16:36:22 +01:00

3.2 KiB
Raw Permalink Blame History

Troubleshooting

Common problems and how to fix them.

1. "API key not found" or "Invalid API key"

What happened: The .env file is missing, in the wrong place, or the key was copied incorrectly.

Fix: Open the .env file in your project folder. Check that:

  • The file is named exactly .env (not env.txt or .env.txt)
  • There are no spaces around the = sign
  • The key is complete (no missing characters from copy-paste)

Tell Claude Code: "Check if my .env file is set up correctly."

2. "Module not found" or dependency errors

What happened: The project dependencies were not installed.

Fix: Tell Claude Code: "Install the project dependencies." It will run the right install command for you.

3. Image search returns bad results

What happened: The image descriptions are too vague.

Fix: Open descriptions.md and improve the descriptions. Compare your descriptions to the "good" examples in that file. Then tell Claude Code: "Re-index the images with the updated descriptions."

4. PDF content is not showing up in search

What happened: The PDF might be scanned (image-based) rather than text-based, or it might be too large.

Fix: Tell Claude Code: "Check if the PDFs contain extractable text." If a PDF is image-based, Claude Code can use OCR to extract the text.

5. Search is slow

What happened: This is normal for the first search after starting the app. The system needs to load.

Fix: Wait a few seconds. Subsequent searches will be faster. If it stays slow, tell Claude Code: "The search is slow. Can you optimize the query?"

6. "Rate limit exceeded" from Google

What happened: You sent too many requests too quickly.

Fix: Wait one minute and try again. The free tier allows 1,500 requests per day but has a per-minute limit too. For the example files in this guide, you should never hit this limit.

7. Pinecone index not found

What happened: The index name in your code does not match what you created in Pinecone.

Fix: Log into pinecone.io, check your index name, and tell Claude Code: "My Pinecone index is named [your-index-name]. Update the configuration."

8. Claude Code asks me something I do not understand

What happened: Claude Code sometimes asks technical questions about implementation choices.

Fix: You can safely answer with: "Use the simplest option" or "You decide, I trust your judgment." Claude Code will pick sensible defaults.

9. The app works but results are not great

What happened: Search quality depends on the descriptions and the chunking strategy.

Fix: Three things to try:

  1. Improve your image descriptions (this makes the biggest difference)
  2. Tell Claude Code: "The search results are not relevant enough. Can you adjust the chunking or add re-ranking?"
  3. Try rephrasing your search query in different ways

10. Something else is broken

Tell Claude Code exactly what you see. Copy-paste the error message. Claude Code is very good at diagnosing and fixing problems when you give it the exact error text.

If you are stuck, you can also start fresh: tell Claude Code "Let's start over. Delete the current search index and re-build everything from scratch."