## TL;DR
Pinecone returns 404 because the index name in your code doesnt exist in the project and region your API key points to. List indexes to confirm, create the index (or fix the name), and make sure the client targets the same environment the index lives in.

```text
pinecone PineconeApiException 404: index not found
```

## Use this when
- Pinecone calls fail with a 404 index not found
- An agent references an index nobody created
- Code moved between projects or regions and broke

## Not for this skill when
- The index exists but vectors are rejected on dimensions (thats a model mismatch)
- The API key is rejected (thats auth)
- You hit quota or rate limits (thats capacity)

## Steps

1. List the indexes your key can see:

```python
from pinecone import Pinecone
pc = Pinecone()
print([i.name for i in pc.list_indexes()])
```
Expected output: the real index names. If yours isnt listed, it doesnt exist for this key and project.

2. Create the index if it should exist, matching your embedding dimension:

```python
pc.create_index(name="docs", dimension=1536, metric="cosine", spec={"serverless": {"cloud": "aws", "region": "us-east-1"}})
```
Expected output: the index appears in the list after it becomes ready. Use the dimension your embed model actually produces.

3. Check the environment. A key from one Pinecone project cant see another project's indexes:

```bash
echo $PINECONE_API_KEY | cut -c1-8
```
Expected output: the key prefix matches the project where the index lives. Swapped keys between dev and prod are a classic cause.

4. Wait for readiness after creation before writing:

```python
import time
while not pc.describe_index("docs").status["ready"]:
    time.sleep(2)
```
Expected output: the loop exits when the index is ready. Writing during provisioning can also surface as 404.

## Variant phrasings

### 404 on query but upsert worked
Youre querying a different index name than you wrote to. Print both names; they differ by a typo.

### index shows in dashboard but API says 404
The API key belongs to a different project than the dashboard you are looking at. Check which project the key is from.

## Why it happens
Pinecone scoping is strict: index names live inside a project, and API keys are project-bound. A typo, a stale name from a deleted index, or a key from the wrong project all produce the same 404. Agents generate index names freely and rarely verify them against the live list, so this is one of the most common Pinecone errors in agent-built pipelines.

## Edge cases
- Index names are lowercase-only with dashes; an uppercase name in code never matches.
- Deleting and recreating an index with a different dimension requires updating the embed model too.
- Serverless and pod-based indexes have different creation specs; a 404 during creation usually means the spec was rejected, so check the create call's own error.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_TO8L7GJyKDvqEkVESNM-zw