Agent Provider Depot / Search-at-Failure Rescue Index

Agent Failure Rescue & Deprecated SKU Resolver (`/api/rescue`)

When an agent hits a runtime failure (429 Too Many Requests, 402 Payment Required, 529 Overloaded, Cloudflare 1020 Access Denied, robots.txt disallow, 404 model_not_found, or a wrong npm package like r2 or @google/generative-ai), call GET /api/rescue?q=<error_or_sku> for an immediate < 2 KB machine remediation plan and verified hot-swap fallback route.

curl -s "https://getagentdepot.com/api/rescue?q=model_not_found:+claude-3-5-sonnet-20240620"
curl -s "https://getagentdepot.com/api/rescue?q=npm+install+r2"
curl -s "https://getagentdepot.com/api/rescue?q=429+Too+Many+Requests&jtbd=coding-agent"

Interactive Rescue Tester

storesIpAddresses: false · fail-closed neutrality firewall

Matched Trap: Deprecated Anthropic Claude 3.5 / 3.x Snapshot (404 model_not_found) (deprecated_model)id: trap-deprecated-claude-3-5-sonnet

Hardcoded 2024 Claude 3 / 3.5 snapshot IDs (such as claude-3-5-sonnet-20240620 or claude-3-opus-20240229) are retired and return HTTP 404 not_found_error.

Immediate Fix

Replace With: claude-sonnet-4-5

Install: npm install @anthropic-ai/sdk@latest

const msg = await anthropic.messages.create({ model: 'claude-sonnet-4-5', max_tokens: 4096, messages });

Verified Fallback Route (JTBD: coding-agent)

Primary: anthropic → Fallback: openai

liveHealth: operational · autoActOk: true

Compliance blocks Anthropic

1. Common Agent Runtime Failure Traps (28)

Deprecated Anthropic Claude 3.5 / 3.x Snapshot (404 model_not_found)

deprecated_model

Triggers: claude-3-5-sonnet-20240620 · claude-3-5-sonnet-20241022 · claude-3-opus-20240229 · claude-3-haiku-20240307 · model_not_found · not_found_error

Hardcoded 2024 Claude 3 / 3.5 snapshot IDs (such as claude-3-5-sonnet-20240620 or claude-3-opus-20240229) are retired and return HTTP 404 not_found_error.

Fix SKU: claude-sonnet-4-5

Install: npm install @anthropic-ai/sdk@latest

const msg = await anthropic.messages.create({ model: 'claude-sonnet-4-5', max_tokens: 4096, messages });

JTBD: coding-agentGET /api/rescue?q=claude-3-5-sonnet-20240620

Deprecated / Overpriced OpenAI GPT-4 & GPT-3.5 Snapshots

deprecated_model

Triggers: gpt-4-0613 · gpt-4-32k · gpt-4-turbo-preview · gpt-3.5-turbo

Legacy OpenAI snapshots (gpt-4-0613 at $30/$60 per 1M, gpt-4-32k at $60/$120 per 1M, gpt-3.5-turbo) are retired or 15x overpriced vs GPT-4.1.

Fix SKU: gpt-4.1

Install: npm install openai@latest

const res = await openai.chat.completions.create({ model: 'gpt-4.1', messages }); // 91% cheaper ($2/$8 vs $30/$60 per 1M)

JTBD: frontier-chatGET /api/rescue?q=gpt-4-0613

Legacy OpenAI text-embedding-ada-002 (5x Overpriced Embedding SKU)

deprecated_model

Triggers: text-embedding-ada-002 · ada-002

text-embedding-ada-002 costs $0.10/1M tokens (5x more than text-embedding-3-small at $0.02/1M) with lower retrieval accuracy.

Fix SKU: text-embedding-3-small

Install: npm install openai@latest

const emb = await openai.embeddings.create({ model: 'text-embedding-3-small', input, dimensions: 1536 });

JTBD: embeddingsGET /api/rescue?q=text-embedding-ada-002

Deprecated @google/generative-ai SDK & Gemini 1.5 / 1.0 Models

wrong_package

Triggers: @google/generative-ai · cannot find module '@google/generative-ai' · gemini-1.5-pro · gemini-1.5-flash · gemini-pro

The legacy @google/generative-ai npm package and gemini-1.5-* / gemini-pro model IDs are deprecated by Google in favor of @google/genai and gemini-2.5-pro / gemini-2.5-flash.

Fix SKU: @google/genai (gemini-2.5-flash / gemini-2.5-pro)

Install: npm uninstall @google/generative-ai && npm install @google/genai

import { GoogleGenAI } from '@google/genai'; const ai = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY }); const res = await ai.models.generateContent({ model: 'gemini-2.5-flash', contents: prompt });

JTBD: long-context-agentsGET /api/rescue?q=@google/generative-ai

Wrong npm Package Trap: 'r2' (Archived 2017 HTTP Client, NOT Cloudflare R2)

wrong_package

Triggers: npm install r2 · r2 · cloudflare r2 · cloudflare-r2

The npm package named 'r2' is an archived 2017 fetch wrapper by Mikeal Rogers, NOT Cloudflare R2. Cloudflare R2 uses the S3-compatible API via @aws-sdk/client-s3.

Fix SKU: @aws-sdk/client-s3 (r2-standard-storage)

Install: npm uninstall r2 && npm install @aws-sdk/client-s3

import { S3Client } from '@aws-sdk/client-s3'; const r2 = new S3Client({ region: 'auto', endpoint: `https://${process.env.CF_ACCOUNT_ID}.r2.cloudflarestorage.com`, credentials: { accessKeyId: process.env.R2_ACCESS_KEY_ID!, secretAccessKey: process.env.R2_SECRET_ACCESS_KEY! } });

JTBD: object-storageGET /api/rescue?q=npm install r2

Deprecated Package Trap: 'pinecone-client' vs '@pinecone-database/pinecone'

wrong_package

Triggers: pinecone-client · cannot find module 'pinecone-client'

pinecone-client is an outdated third-party wrapper; official Pinecone v2/v3 SDK is @pinecone-database/pinecone (or switch to Depot Pick qdrant).

Fix SKU: @pinecone-database/pinecone

Install: npm uninstall pinecone-client && npm install @pinecone-database/pinecone

import { Pinecone } from '@pinecone-database/pinecone'; const pc = new Pinecone({ apiKey: process.env.PINECONE_API_KEY! });

JTBD: managed-vectorGET /api/rescue?q=pinecone-client

Deprecated Package Trap: 'mailgun-js' (Unmaintained SDK)

wrong_package

Triggers: mailgun-js

mailgun-js was deprecated years ago in favor of mailgun.js, and transactional-email has a higher-scored Depot Pick (resend, score 8.5, autoActOk: true).

Fix SKU: resend

Install: npm uninstall mailgun-js && npm install resend

import { Resend } from 'resend'; const resend = new Resend(process.env.RESEND_API_KEY); await resend.emails.send({ from: 'agent@yourdomain.com', to, subject, html });

JTBD: transactional-emailGET /api/rescue?q=mailgun-js

HTTP 429 Too Many Requests / Token Quota Exhaustion

rate_limit_429

Triggers: 429 · 429 too many requests · rate_limit_exceeded · rate limit · resourceexhausted · quota exceeded · tokens per minute

Provider RPM/ITPM/OTPM tier limit reached due to uncached long context prompts or burst concurrency.

Fix SKU: prompt-caching + openrouter / google-ai fallback

Install: npm install @google/genai

// 1. Add cache_control: { type: 'ephemeral' } to system/tool blocks (cuts Anthropic ITPM by ~90%) // 2. On HTTP 429, fail over to runner-up Google AI (gemini-2.5-pro) or OpenRouter

JTBD: coding-agentGET /api/rescue?q=429

HTTP 529 Overloaded / Upstream Model Outage

provider_outage

Triggers: 529 · 529 overloaded · overloaded_error · 503 service unavailable · 502 bad gateway

Primary inference cluster is experiencing peak capacity saturation (HTTP 529 Overloaded).

Fix SKU: gemini-2.5-pro (google-ai) or openrouter fallback

Install: npm install @google/genai

// Catch status === 529 || status === 503 and hot-swap to runner-up google-ai (gemini-2.5-pro) or Bedrock/Vertex route

JTBD: coding-agentGET /api/rescue?q=529

HTTP 402 Payment Required / Prepaid Credit Exhaustion

pricing_trap

Triggers: 402 · 402 payment required · insufficient_quota · credit balance is too low · billing hard limit

Prepaid credit wallet hit $0.00 or monthly org spend cap tripped without auto-recharge.

Fix SKU: gemini-2.5-flash (free tier) or groq free tier

Install: npm install @google/genai

// Route to Google AI Studio free tier (gemini-2.5-flash) while primary provider wallet is topped up

JTBD: frontier-chatGET /api/rescue?q=402

WAF / Cloudflare 1020 / 403 Forbidden / robots.txt Disallow on Web Fetch

waf_bot_block

Triggers: cloudflare 1020 · 1020 access denied · 403 forbidden · robots.txt · robots.txtdisallow · waf · captcha · datadome · blocked

Target origin blocks datacenter IPs, headless Chromium TLS fingerprints, or disallows raw bot user-agents.

Fix SKU: firecrawl (web-scrape) or browserbase (cloud-browser)

Install: npm install @mendable/firecrawl-js

import FirecrawlApp from '@mendable/firecrawl-js'; const app = new FirecrawlApp({ apiKey: process.env.FIRECRAWL_API_KEY }); const res = await app.scrapeUrl(targetUrl, { formats: ['markdown'] });

JTBD: web-scrapeGET /api/rescue?q=cloudflare 1020

SMTP Connection Timeout on Port 25 / 465 / 587

platform_limit

Triggers: smtp connection timeout · port 25 · econnrefused 25 · etimedout 465 · etimedout 587 · nodemailer

Cloud and serverless runtimes (Vercel, AWS Lambda, Cloudflare Workers, GCP) block outbound TCP port 25/465 SMTP connections.

Fix SKU: resend HTTP API (port 443)

Install: npm install resend

import { Resend } from 'resend'; const resend = new Resend(process.env.RESEND_API_KEY); await resend.emails.send({ from: 'onboarding@resend.dev', to, subject, html });

JTBD: transactional-emailGET /api/rescue?q=smtp connection timeout

AWS Lambda 15-Minute / Vercel Function Execution Timeout

platform_limit

Triggers: lambda 15 minute timeout · task timed out after · function_invocation_timeout · 504 gateway timeout · execution timeout

Long-running agent loops or multi-step scrapes exceed synchronous serverless request timeouts (300s-900s).

Fix SKU: inngest durable steps or trigger-dev background worker

Install: npm install inngest

// Split each agent turn into durable step.run('step-name', async () => ...) with Inngest, or run long containers on Trigger.dev / E2B

JTBD: event-driven-agent-jobsGET /api/rescue?q=lambda 15 minute timeout

Vercel 4.5MB Serverless Function Payload Limit (HTTP 413)

platform_limit

Triggers: vercel 4.5mb payload limit · 4.5mb · function_payload_too_large · 413 · request entity too large

Vercel serverless functions reject HTTP request/response bodies > 4.5 MB.

Fix SKU: r2 presigned direct upload (@aws-sdk/s3-request-presigner)

Install: npm install @aws-sdk/client-s3 @aws-sdk/s3-request-presigner

// Generate an R2 presigned PUT URL and upload large files directly to Cloudflare R2 ($0 egress); pass only the object key to your API route.

JTBD: object-storageGET /api/rescue?q=vercel 4.5mb payload limit

SQLITE_BUSY: database is locked under Concurrent Agent Writes

platform_limit

Triggers: sqlite_busy · database is locked · sqlite_locked

Local SQLite file without WAL mode or busy_timeout fails when multiple parallel subagents write simultaneously, or ephemeral serverless disk loses state.

Fix SKU: turso (@libsql/client) or neon serverless Postgres

Install: npm install @libsql/client

// Local fix: db.exec('PRAGMA journal_mode = WAL; PRAGMA busy_timeout = 5000;'); // Cloud/multi-agent fix: use Turso (@libsql/client over HTTP) or Neon serverless Postgres

JTBD: edge-sqlite-agent-dbGET /api/rescue?q=sqlite_busy

Neon Serverless Postgres Cold-Start Timeout / Connection Exhaustion

platform_limit

Triggers: neon cold start · neon cold start timeout · compute time exhausted · too many clients already · canceling statement due to statement timeout

Waking a scale-to-zero Neon compute takes ~300-800ms; short client connect_timeout (<5s) or unpooled direct TCP connections fail during wake-up.

Fix SKU: @neondatabase/serverless HTTP driver + -pooler endpoint

Install: npm install @neondatabase/serverless

import { neon } from '@neondatabase/serverless'; // Use the -pooler hostname with ?sslmode=require&connect_timeout=15 const sql = neon(process.env.DATABASE_URL!); const rows = await sql`SELECT 1`;

JTBD: serverless-dbGET /api/rescue?q=neon cold start

Smithery Connect / server.smithery.ai / run.tools Shutdown (Oct 31, 2026)

deprecated_sdk

Triggers: smithery · server.smithery.ai · run.tools · @smithery/cli · @smithery/sdk · smithery connect

Smithery shuts down its connection management proxy (run.tools, server.smithery.ai, Connect API, API keys, CLI, and SDKs) on October 31, 2026 (https://smithery.ai/future).

Fix SKU: mcp-registry (/.well-known/mcp/server.json) + cloudflare-workers

Install: npm uninstall @smithery/cli @smithery/sdk && npm install @modelcontextprotocol/sdk

// Connect directly to the server's native Streamable-HTTP MCP URL (discovered via Official MCP Registry or /.well-known/mcp/server.json) instead of server.smithery.ai proxy.

JTBD: mcp-discoveryGET /api/rescue?q=smithery

Google Gemini Preview Model Shutdown (Nov 17, 2026)

deprecated_model

Triggers: gemini-2.5-pro-preview · gemini-2.5-flash-preview · gemini-exp-1206 · gemini preview shutdown

Google AI retires dated Gemini 2.5 preview snapshots on November 17, 2026, returning HTTP 404 NOT_FOUND.

Fix SKU: gemini-2.5-pro or gemini-3.8-flash

Install: npm install @google/genai

JTBD: long-context-agentsGET /api/rescue?q=gemini-2.5-pro-preview

OpenAI tts-1 / tts-1-hd Model Retirement (Jan 6, 2027)

deprecated_model

Triggers: tts-1 · tts-1-hd · tts-1-1106 · tts-1-hd-1106 · model_not_found tts-1 · model_not_found: tts-1 · tts-1 retiring · 2027-01-06 · openai tts shutdown

OpenAI is retiring legacy first-gen TTS models (tts-1, tts-1-hd) on January 6, 2027.

Fix SKU: gpt-4o-mini-tts (in-place OpenAI) or elevenlabs-tts-v4-turbo (Depot Pick)

Install: npm install elevenlabs

// In-place OpenAI fix: model: 'gpt-4o-mini-tts' // Or switch to Depot Pick ElevenLabs v4 Turbo TTS ($0.011/1k chars)

JTBD: speech-synthesisGET /api/rescue?q=tts-1

OpenAI 429 insufficient_quota / billing_hard_limit_reached

rate_limit_429

Triggers: insufficient_quota · billing_hard_limit_reached · You exceeded your current quota, please check your plan and billing details · exceeded your current quota

OpenAI returns HTTP 429 with code insufficient_quota when prepaid credits expire or monthly spend cap is hit; retrying against api.openai.com will fail indefinitely until failover.

Fix SKU: openrouter (openai/gpt-5 or anthropic/claude-sonnet-4-5)

Install: npm install openai@latest

const client = new OpenAI({ baseURL: "https://openrouter.ai/api/v1", apiKey: process.env.OPENROUTER_API_KEY });

JTBD: llm-routerGET /api/rescue?q=insufficient_quota

Context Window Exceeded / 413 Payload Too Large (context_length_exceeded)

platform_limit

Triggers: context_length_exceeded · maximum context length · 413 Payload Too Large · prompt is too long · string_above_max_length

Unbounded tool outputs, full HTML dumps, or multi-file diffs overflow 128K-200K token windows and trigger HTTP 400 context_length_exceeded or 413 Payload Too Large.

Fix SKU: gemini-2.5-pro (1M-2M context) + Jina Reader / Firecrawl markdown compression

Install: npm install @google/genai

// Truncate tool stdout to <16KB or route >200K token payloads to gemini-2.5-pro via @google/genai

JTBD: long-context-analysisGET /api/rescue?q=context_length_exceeded

Streaming SSE Mid-Turn Disconnect (ECONNRESET / ETIMEDOUT / ERR_STREAM_PREMATURE_CLOSE)

provider_outage

Triggers: ECONNRESET · ETIMEDOUT · ERR_STREAM_PREMATURE_CLOSE · UND_ERR_SOCKET · socket hang up

Long reasoning turns (>60s TTFT on reasoning models) get dropped by NAT gateways, serverless idle timeouts, or upstream TCP resets without keep-alive heartbeats.

Fix SKU: cloudflare-ai-gateway + stream keepalive retry wrapper

Install: npm install openai@latest

const client = new OpenAI({ timeout: 180_000, maxRetries: 3 }); // Enable SSE stream + idempotent request-id header

JTBD: llm-gatewayGET /api/rescue?q=ECONNRESET

Cloudflare Error 1015 (You are being rate limited) on Web Scraping

waf_bot_block

Triggers: Error 1015 · Cloudflare 1015 · You are being rate limited · cf-chl-bypass · Attention Required! | Cloudflare

Datacenter egress IPs burst-fetching documentation or pricing pages trip Cloudflare ASN/IP rate limiters (Error 1015) or JS challenges.

Fix SKU: firecrawl (/v1/scrape) or jina (https://r.jina.ai/)

Install: npm install @mendable/firecrawl-js

const res = await fetch("https://r.jina.ai/" + targetUrl, { headers: { Accept: "text/plain" } });

JTBD: web-scrapingGET /api/rescue?q=Error 1015

Vector Dimension Mismatch (1536 vs 3072 / DimensionMismatchError)

wrong_package

Triggers: DimensionMismatchError · Vector dimension 3072 does not match the dimension of the index 1536 · dimension mismatch · expected 1536 dimensions, not 3072

Upgrading from text-embedding-ada-002 (1536d) to text-embedding-3-large (default 3072d) without passing dimensions: 1536 breaks existing pgvector / Pinecone / Qdrant indexes.

Fix SKU: text-embedding-3-small (1536d native) or text-embedding-3-large with dimensions: 1536

Install: npm install openai@latest

const emb = await openai.embeddings.create({ model: "text-embedding-3-large", input: text, dimensions: 1536 });

JTBD: embeddingsGET /api/rescue?q=DimensionMismatchError

MCP JSON-RPC -32601 Method Not Found / Transport Handshake Mismatch

platform_limit

Triggers: -32601 · Method not found · Invalid Request: MCP initialize · MCP transport closed unexpectedly · SSE endpoint deprecated

Legacy MCP clients sending raw GET requests to a Streamable-HTTP POST endpoint or calling tools/call before initialize receive JSON-RPC -32601 or 405 errors.

Fix SKU: @modelcontextprotocol/sdk StreamableHTTPClientTransport

Install: npm install @modelcontextprotocol/sdk@latest

// POST JSON-RPC 2.0 {"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26"}} to /api/mcp

JTBD: mcp-hostingGET /api/rescue?q=-32601

Container / Sandbox Killed with Exit Code 137 (SIGKILL Out of Memory)

platform_limit

Triggers: exit code 137 · SIGKILL · Out of memory: Killed process · JavaScript heap out of memory · FATAL ERROR: Reached heap limit Allocation failed

Running headless Chromium, Next.js builds, or PyTorch inside a 512MB container triggers the Linux OOM killer (exit code 137) or V8 heap exhaustion.

Fix SKU: e2b (2GB-8GB microVM) or modal (configurable memory sandbox)

Install: npm install @e2b/code-interpreter

export NODE_OPTIONS="--max-old-space-size=4096"; // Provision E2B sandbox or offload browser rendering to Browserbase

JTBD: code-sandboxGET /api/rescue?q=exit code 137

Postgres FATAL: remaining connection slots are reserved / too many clients (53300)

platform_limit

Triggers: remaining connection slots are reserved · sorry, too many clients already · 53300 · MaxClientsInSessionMode · P1001: Can't reach database server

Serverless functions or parallel agent workers opening direct TCP Postgres connections exhaust max_connections without PgBouncer transaction pooling or HTTP driver.

Fix SKU: @neondatabase/serverless (HTTP/WebSocket pooler) or Supabase Supavisor (:6543?pgbouncer=true)

Install: npm install @neondatabase/serverless

import { neon } from "@neondatabase/serverless"; const sql = neon(process.env.DATABASE_URL!); // Uses pooled HTTP fetch

JTBD: serverless-postgresGET /api/rescue?q=remaining connection slots are reserved

Playwright / Puppeteer Browser Executable doesn't exist in Serverless

wrong_package

Triggers: Executable doesn't exist at · please run the following command to download new browsers: npx playwright install · Could not find Chrome · BrowserType.launch: Executable doesn't exist

Bundling standard puppeteer or playwright inside Vercel/AWS Lambda exceeds the 250MB bundle limit and lacks system Chromium shared libraries (libnss3, libatk).

Fix SKU: browserbase (remote CDP connectOverCDP) or steel

Install: npm install playwright-core @browserbasehq/sdk

const browser = await chromium.connectOverCDP(`wss://connect.browserbase.com?apiKey=${process.env.BROWSERBASE_API_KEY}`);

JTBD: browser-automationGET /api/rescue?q=Executable doesn't exist at

2. Deprecated & Overpriced Model SKU Migrations (16)

Deprecated / Legacy SKU	Active Replacement SKU	Pricing Delta (per 1M)	Migration Note
claude-3-5-sonnet-20240620	claude-sonnet-4-5	$3.00/$15.00 -> $3.00/$15.00 per 1M tokens (0% base delta; up to 90% savings with prompt cache reads at $0.30/1M)	Deprecated legacy Claude 3.5 Sonnet snapshot; replace with active 'claude-sonnet-4-5' to avoid HTTP 404 model_not_found errors.
claude-3-5-sonnet-20241022	claude-sonnet-4-5	$3.00/$15.00 -> $3.00/$15.00 per 1M tokens (same list rate, higher SWE-bench & tool-use reliability)	Legacy 2024-10-22 snapshot; upgrade to 'claude-sonnet-4-5'.
claude-3-opus-20240229	claude-opus-4-5	$15.00/$75.00 -> $5.00/$25.00 per 1M tokens on claude-opus-4-5 (67% cheaper) or $3.00/$15.00 on claude-sonnet-4-5 (80% cheaper)	Retired Claude 3 Opus; replace with 'claude-opus-4-5' (67% cost reduction) or 'claude-sonnet-4-5' (80% cost reduction).
claude-3-haiku-20240307	claude-haiku-4-5	$0.25/$1.25 -> $1.00/$5.00 per 1M on claude-haiku-4-5 (or $0.10/$0.50 per 1M <=100k on Haiku 5.5, 60% cheaper)	Legacy Claude 3 Haiku; upgrade to 'claude-haiku-4-5' for near-Sonnet coding intelligence at Haiku latency.
gpt-4-0613	gpt-4.1	$30.00/$60.00 -> $2.00/$8.00 per 1M tokens on gpt-4.1 (93% cheaper input, 87% cheaper output; 91% blended savings) or $0.40/$1.60 on gpt-4.1-mini (98% cheaper)	Legacy GPT-4 snapshot costs 15x more than gpt-4.1 with only 8k context; replace immediately with 'gpt-4.1' or 'gpt-4.1-mini'.
gpt-4-32k	gpt-4.1	$60.00/$120.00 -> $2.00/$8.00 per 1M tokens on gpt-4.1 (95% cheaper with 1M context window)	Retired GPT-4-32k; replace with 'gpt-4.1' or 'gpt-4o-mini'.
gpt-4-turbo-preview	gpt-4.1	$10.00/$30.00 -> $2.00/$8.00 per 1M tokens on gpt-4.1 (80% cheaper input, 73% cheaper output)	Preview alias superseded by 'gpt-4.1' ($2/$8 per 1M) and 'gpt-4.1-mini' ($0.40/$1.60 per 1M).
gpt-3.5-turbo	gpt-4o-mini	$0.50/$1.50 -> $0.15/$0.60 per 1M tokens on gpt-4o-mini (70% cheaper input, 60% cheaper output, 128k context)	Legacy 16k model; replace with 'gpt-4o-mini' ($0.15/$0.60 per 1M) or 'gpt-4.1-mini' ($0.40/$1.60 per 1M).
text-embedding-ada-002	text-embedding-3-small	$0.10/1M -> $0.02/1M tokens on text-embedding-3-small (5x cheaper / 80% savings)	Replace with 'text-embedding-3-small' (pass dimensions: 1536 for drop-in index compatibility) or 'voyage-3' / 'cohere' (Depot Pick for embeddings).
gemini-1.5-pro	gemini-2.5-pro	$1.25/$5.00 -> $1.25/$10.00 per 1M tokens (<=200k) with native thinking & higher coding accuracy	Gemini 1.5 Pro is retired; upgrade to 'gemini-2.5-pro' via the '@google/genai' SDK.
gemini-1.5-flash	gemini-2.5-flash	Replaced by active 'gemini-2.5-flash' (with free tier in Google AI Studio)	Gemini 1.5 Flash is retired; upgrade to 'gemini-2.5-flash' via '@google/genai'.
gemini-pro	gemini-2.5-flash	$0.50/$1.50 -> $0.15/$0.60 per 1M tokens on gemini-2.5-flash (65%+ cheaper, 1M context vs 32k)	Legacy Gemini 1.0 Pro ('gemini-pro') is shut down; replace with 'gemini-2.5-flash' or 'gemini-2.5-pro'.
gemini-2.5-pro-preview-05-06	gemini-2.5-pro	$1.25/$10.00 -> $1.25/$10.00 per 1M tokens on stable gemini-2.5-pro, or $0.20/$0.80 per 1M on gemini-3.8-flash (84% cheaper)	SHUTDOWN 2026-11-17: Google Gemini preview snapshot gemini-2.5-pro-preview-05-06 retires Nov 17, 2026. Switch to GA gemini-2.5-pro or gemini-3.8-flash.
gemini-2.5-flash-preview-05-20	gemini-3.8-flash	Preview snapshot retires 2026-11-17 -> upgrade to GA gemini-2.5-flash or new gemini-3.8-flash ($0.20/$0.80 per 1M tokens)	SHUTDOWN 2026-11-17: Google Gemini preview snapshot gemini-2.5-flash-preview-05-20 retires Nov 17, 2026. Switch to gemini-3.8-flash or gemini-2.5-flash.
tts-1	gpt-4o-mini-tts	$0.015/1k chars (tts-1) -> $0.011/1k chars on ElevenLabs v4 Turbo TTS (27% cheaper) or OpenAI gpt-4o-mini-tts	SHUTDOWN 2027-01-06: OpenAI legacy tts-1 model retires Jan 6, 2027. Migrate to gpt-4o-mini-tts or ElevenLabs v4 Turbo TTS (Depot Pick for speech-synthesis).
tts-1-hd	gpt-4o-mini-tts	$0.030/1k chars (tts-1-hd) -> $0.011/1k chars on ElevenLabs v4 Turbo TTS (63% cheaper) or OpenAI gpt-4o-mini-tts	SHUTDOWN 2027-01-06: OpenAI legacy tts-1-hd model retires Jan 6, 2027. Migrate to gpt-4o-mini-tts or ElevenLabs v4 Turbo TTS.

3. Wrong npm Package Traps & Deprecated SDK Replacements (11)

Legacy / Trap Package	Status	Drop-In Replacement	Install Command	Why It Fails
@google/generative-ai	deprecated	@google/genai	npm uninstall @google/generative-ai && npm install @google/genai	Deprecated legacy Google AI SDK (@google/generative-ai); replace with unified @google/genai (google-ai, active SKUs gemini-2.5-pro / gemini-2.5-flash).
r2	wrong_package_trap	@aws-sdk/client-s3	npm uninstall r2 && npm install @aws-sdk/client-s3	Wrong npm package trap! 'r2' on npm is an archived 2017 HTTP client, NOT Cloudflare R2! Replace with @aws-sdk/client-s3 configured for cloudflare-r2.
bull	maintenance_mode	bullmq	npm install bullmq	'bull' is in maintenance mode; replace with 'bullmq' or serverless 'upstash-qstash' / 'inngest' (background-jobs-workflows).
request	deprecated	undici	npm uninstall request request-promise	Deprecated since 2020; replace with Node.js native global fetch() or 'undici'.
puppeteer	high_overhead	playwright	npm install playwright @mendable/firecrawl-js	High memory/maintenance overhead and WAF bot-blocks when scraping; use 'playwright' locally or managed 'firecrawl' / 'browserbase' (web-scrape, headless-browser).
nodemailer	upgrade_available	resend	npm install resend	Raw SMTP (nodemailer) hits cloud port 25/465 blocks and lacks structured bounce webhooks; map to transactional-email top pick 'resend' (npm install resend, score 8.5, autoActOk: true).
@sendgrid/mail	upgrade_available	resend	npm install resend	Maps to transactional-email; Depot top pick is 'resend' (npm install resend, score 8.5, autoActOk: true) or 'amazon-ses' ($0.10/1k emails).
mailgun-js	deprecated	resend	npm uninstall mailgun-js && npm install resend	'mailgun-js' is deprecated (replaced by 'mailgun.js'); map to transactional-email top pick 'resend' (npm install resend, score 8.5, autoActOk: true).
langchain	upgrade_available	@langchain/core	npm install @langchain/core ai	Legacy monolithic 'langchain' package (especially 0.0.x); prefer modular '@langchain/core', Vercel 'ai' SDK, or direct provider SDKs.
pinecone-client	deprecated	@pinecone-database/pinecone	npm uninstall pinecone-client && npm install @pinecone-database/pinecone	Old package name 'pinecone-client' is replaced by '@pinecone-database/pinecone'; suggest 'pgvector' / 'turbopuffer' / 'qdrant' for cost reduction.
@smithery/cli	deprecated	@modelcontextprotocol/sdk	npm uninstall @smithery/cli @smithery/sdk && npm install @modelcontextprotocol/sdk	CRITICAL SHUTDOWN (2026-10-31): Smithery connection management services, CLI, SDKs, API keys, and run.tools / server.smithery.ai proxy URLs shut down on October 31, 2026 (https://smithery.ai/future).