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: GROQAPIKEY 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 $GROQAPIKEY. Get a key at

. See

the Authentication section of

references/implementation.md.

Model Deprecation Timeline

Groq announces deprecations with advance notice. These models have been deprecated:

Current Model IDs (Use These)

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.

1. 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.

1. Upgrade the SDK — git checkout -b chore/upgrade-groq-sdk, then

npm install groq-sdk@latest.

1. 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.

1. Run the migration scanner — the grep sweep in the reference flags

deprecated model IDs, old @groq/sdk imports, and removed method calls.

1. Validate and test — npm test, then confirm current IDs against the live

/v1/models endpoint and run the SDK integration smoke test.

1. 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",
  // ...full map in references/implementation.md
};

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

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

• Full walkthrough (all commands)
• Worked examples
• Groq Model Deprecations
• Groq Changelog
• groq-sdk GitHub Releases
• Groq Current Models

For CI integration during upgrades, see the groq-ci-integration skill.