Groq Upgrade & Migration
Current State
!npm list groq-sdk 2>/dev/null | grep groq-sdk || echo 'groq-sdk not installed'
!pip show groq 2>/dev/null | grep -E "Name|Version" || echo 'groq not installed (python)'
Overview
Guide for upgrading the groq-sdk package and migrating away from deprecated
model IDs. It walks a safe upgrade path — branch, bump, scan for deprecated
model references, rewrite them, and verify against the live models endpoint
before merging.
Prerequisites
- A Node project that depends on
groq-sdk (or the Python groq package).
npm, git, curl, and jq available on PATH.- Authentication:
GROQ_API_KEY exported in your shell (or CI secret
store). The SDK constructor new Groq() reads it automatically; the live
model check passes it as Authorization: Bearer $GROQ_API_KEY. Get a key at
https://console.groq.com/keys. See
the Authentication section of
references/implementation.md.
Model Deprecation Timeline
Groq announces deprecations with advance notice. These models have been deprecated:
| Deprecated Model | Deprecation Date | Replacement |
|---|
mixtral-8x7b-32768 | 2025-03-05 | llama-3.3-70b-versatile or llama-3.1-8b-instant |
gemma2-9b-it | 2025-08-08 | llama-3.1-8b-instant |
llama-3.1-70b-versatile | 2024-12-06 | llama-3.3-70b-versatile |
llama-3.1-70b-specdec | 2024-12-06 | llama-3.3-70b-specdec |
playai-tts | 2025-12-23 | Orpheus TTS models |
playai-tts-arabic | 2025-12-23 | Orpheus TTS models |
distil-whisper-large-v3-en | — | whisper-large-v3-turbo |
Current Model IDs (Use These)
| Model ID | Type | Context | Speed |
|---|
llama-3.1-8b-instant | Text | 128K | ~560 tok/s |
llama-3.3-70b-versatile | Text | 128K | ~280 tok/s |
llama-3.3-70b-specdec | Text | 128K | Faster |
meta-llama/llama-4-scout-17b-16e-instruct | Vision+Text | 128K | ~460 tok/s |
meta-llama/llama-4-maverick-17b-128e-instruct | Vision+Text | 128K | — |
whisper-large-v3 | Audio STT | — | 164x RT |
whisper-large-v3-turbo | Audio STT | — | 216x RT |
Always verify against the live endpoint: GET https://api.groq.com/openai/v1/models.
Instructions
Work through these six steps. Each has a copy-paste command block in
references/implementation.md; the summary here is
enough to drive the workflow, then drill in for the exact commands.
- Check current version and models — read the installed
groq-sdk version,
compare to npm view groq-sdk version, and grep your src/ for every
model string reference.
- Upgrade the SDK —
git checkout -b chore/upgrade-groq-sdk, then
npm install groq-sdk@latest.
- Find and replace deprecated models — use
Read/Edit to fold the
MODEL_MIGRATIONS resolver map (below) into your Groq client module, or
Write a new groq-migrations.ts helper, so deprecated IDs are rewritten
at runtime.
- Run the migration scanner — the
grep sweep in the reference flags
deprecated model IDs, old @groq/sdk imports, and removed method calls.
- Validate and test —
npm test, then confirm current IDs against the live
/v1/models endpoint and run the SDK integration smoke test.
- Roll back if needed — pin the previous version with
npm install groq-sdk@0.11.0 --save-exact and re-run tests.
The essential resolver skeleton (full version in the reference):
const MODEL_MIGRATIONS: Record<string, string> = {
"mixtral-8x7b-32768": "llama-3.3-70b-versatile",
"gemma2-9b-it": "llama-3.1-8b-instant",
"distil-whisper-large-v3-en": "whisper-large-v3-turbo",
};
function resolveModel(model: string): string {
if (model in MODEL_MIGRATIONS) {
console.warn(`Model ${model} is deprecated. Using ${MODEL_MIGRATIONS[model]} instead.`);
return MODEL_MIGRATIONS[model];
}
return model;
}
Output
Running this workflow produces:
- A
chore/upgrade-groq-sdk branch with groq-sdk bumped in package.json and
the lockfile.
- A scanner report listing any remaining deprecated model IDs, stale
@groq/sdk imports, or removed method calls — empty under every heading means
the code is clean.
- Updated call sites (or a
resolveModel wrapper) pointing at current model IDs.
- A green
npm test run plus a live /v1/models listing confirming every model
your code uses is still served.
Error Handling
| Issue | Symptom | Solution |
|---|
| Deprecated model | 400 model_not_found or 400 model_decommissioned | Replace with current model ID |
| Type errors after upgrade | TypeScript compilation fails | Check SDK changelog for type changes |
| Auth format change | 401 after upgrade | Verify constructor uses apiKey, not key, and GROQ_API_KEY is set |
| New required fields | 400 on previously working requests | Check API docs for parameter changes |
Examples
Worked before/after migrations — replacing a decommissioned chat model, routing
every call through resolveModel, migrating a transcription model, and reading a
clean scanner run — are in
references/examples.md. Quick example: a call still
using mixtral-8x7b-32768 swaps to llama-3.3-70b-versatile per the migration
map, clearing the 400 model_decommissioned error.
Resources
For CI integration during upgrades, see the groq-ci-integration skill.
