stream-chat: tokens can only be created server-side using the API Secret (Next.js API route)

TL;DR

Fix: use new StreamChat(apiKey, apiSecret) in your API route instead of getInstance, which always creates a fresh instance with the credentials you pass.

Steps

1. In a Next.js API route (server-side code), calling client.createToken(userId) on a client from StreamChat.getInstance(process.env.STREAM_KEY, process.env.STREAM_SECRET) throws Error: tokens can only be created server-side using the API Secret, even though the secret is passed. The key and secret env vars are correctly set, and the reporter confirmed they are read properly. The client instance reports secret value == undefined despite the secret being passed to getInstance.
2. StreamChat.getInstance() is a singleton: it creates the client only on the first call in the runtime, and later calls with different parameters are ignored. If the client was first initialized anywhere without the secret (e.g. client-side code), the shared instance has secret value == undefined and token creation throws. Fix: use new StreamChat(apiKey, apiSecret) in your API route instead of getInstance, which always creates a fresh instance with the credentials you pass. The maintainer confirmed this is the correct approach when you need different instances/key-secrets.

Expected: The maintainer confirmed this is the correct approach when you need different instances/key-secrets.

When to use

You are seeing this: In a Next.js API route (server-side code), calling client.createToken(userId) on a client from StreamChat.getInstance(process.env.STREAM\KEY, process.env.STREAM\SECRET) throws Error: tokens can only be created server-side using the API Secret, even... Use this skill when you run into "stream-chat: tokens can only be created server-side using the API Secret (Next.js API route)".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

Question asked in the thread: In a Next.js API route (server-side code), calling client.createToken(userId) on a client from StreamChat.getInstance(process.env.STREAM_KEY, process.env.STREAM_SECRET) throws Error: tokens can only be created server-side using the API Secret, even though the secret is passed. The key and secret env vars are correctly set, and the reporter confirmed they are read properly. The client instance reports secret value == undefined despite the secret being passed to getInstance.

Verified answer: StreamChat.getInstance() is a singleton: it creates the client only on the first call in the runtime, and later calls with different parameters are ignored. If the client was first initialized anywhere without the secret (e.g. client-side code), the shared instance has secret value == undefined and token creation throws. Fix: use new StreamChat(apiKey, apiSecret) in your API route instead of getInstance, which always creates a fresh instance with the credentials you pass. The maintainer confirmed this is the correct approach when you need different instances/key-secrets. Source: https://github.com/GetStream/stream-chat-js/issues/665

Thread: https://vectle.com/threads/thrEXdKwVboyyhE2OXdeK71A