ChatGPTNextWeb/NextChat · error · Error

😆 Oops, there's an issue. Let's fix it: \ 1️⃣ New here

Error message

😆 Oops, there's an issue. Let's fix it:
     \ 1️⃣ New here? [Click to start chatting now 🚀](${SAAS_CHAT_UTM_URL})
     \ 2️⃣ Using a private setup? [Click here](/#/auth) to enter your key 🔑
     \ 3️⃣ Want to use your own OpenAI resources? [Click here](/#/settings) to change settings ⚙️
     

What it means

This is the localized Locale.Error.Unauthorized string, thrown at openai.ts:460 when the HTTP status of the OpenAI 'dashboard/billing/usage' request is exactly 401. It is the user-facing 'enter your key / change settings' message that NextChat surfaces whenever the API rejects the request as unauthenticated. The 401 short-circuits before the generic 'failed to query usage' check on line 463-464.

Source

Thrown at app/client/platforms/openai.ts:460

    const [used, subs] = await Promise.all([
      fetch(
        this.path(
          `${OpenaiPath.UsagePath}?start_date=${startDate}&end_date=${endDate}`,
        ),
        {
          method: "GET",
          headers: getHeaders(),
        },
      ),
      fetch(this.path(OpenaiPath.SubsPath), {
        method: "GET",
        headers: getHeaders(),
      }),
    ]);

    if (used.status === 401) {
      throw new Error(Locale.Error.Unauthorized);
    }

    if (!used.ok || !subs.ok) {
      throw new Error("Failed to query usage from openai");
    }

    const response = (await used.json()) as {
      total_usage?: number;
      error?: {
        type: string;
        message: string;
      };
    };

    const total = (await subs.json()) as {
      hard_limit_usd?: number;
    };

View on GitHub (pinned to defdcdb55d)

Solutions

1. Open Settings (/#/settings) and confirm the OpenAI API Key field is filled with a valid sk- key that is active on platform.openai.com.
2. If using a custom base URL / proxy, verify it accepts the same Authorization header and does not return 401 for the dashboard/billing/* paths.
3. If using Azure, switch ServiceProvider to Azure in settings so the Azure-specific paths are used instead of the OpenAI billing paths.
4. Regenerate the key on platform.openai.com if it was revoked, then re-paste it and reload.
5. If the deployment cannot reach api.openai.com at all, use the SaaS chat endpoint linked in the error message.

Example fix

// before
if (used.status === 401) {
  throw new Error(Locale.Error.Unauthorized);
}

// after — distinguish auth failure from missing billing endpoint so the real cause is visible
if (used.status === 401 || subs.status === 401) {
  throw new Error(Locale.Error.Unauthorized);
}
if (used.status === 404 || subs.status === 404) {
  // billing endpoints were removed from api.openai.com; treat as 'usage unavailable'
  return { used: undefined, total: undefined } as LLMUsage;
}

import { useAccessStore } from "@/app/client";

function hasOpenaiKey(): boolean {
  const access = useAccessStore.getState();
  const key = access.openaiApiKey;
  return typeof key === "string" && key.trim().startsWith("sk-") && key.length > 20;
}

// before calling usage()
if (!hasOpenaiKey()) {
  throw new Error(Locale.Error.Unauthorized); // or route user to settings
}

function isOpenaiAuthFailure(res: Response): boolean {
  return res.status === 401;
}

try {
  const usage = await openai.usage();
} catch (e) {
  if (e instanceof Error && e.message === Locale.Error.Unauthorized) {
    // route to /#/auth or /#/settings
  } else {
    throw e;
  }
}

When it happens

Trigger: The usage() method issues GET requests to OpenaiPath.UsagePath ('dashboard/billing/usage') and OpenaiPath.SubsPath ('dashboard/billing/subscription'). If the 'used' response has status === 401 — invalid/expired API key, empty OPENAI_API_KEY, wrong base URL pointing at a proxy that returns 401, or a key without billing scope — this error is thrown immediately.

Common situations: First-time NextChat setup with no key configured; key rotated/expired on the OpenAI dashboard; user switched from the SaaS endpoint to a custom proxy but did not re-enter the key; Azure OpenAI base URL used against the openai.com billing path; key has access to chat completions but the proxy strips billing endpoints and returns 401.

Related errors

• Failed to query usage from openai

AI-assisted analysis of ChatGPTNextWeb/NextChat@defdcdb55d (2026-08-12). Data as JSON: /api/errors/9fb697019fff017a. Report an issue: GitHub.