# 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."
