edcd1721df
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.
96 lines
3.2 KiB
Markdown
96 lines
3.2 KiB
Markdown
# 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."
|