bytedance/deer-flow · info

Failed to load thread token usage.

Error message

Failed to load thread token usage.

What it means

Thrown when GET /api/threads/{id}/token-usage fails with a status other than 403/404 (those deliberately return null because older or restricted backends don't expose usage). The endpoint aggregates model token usage per thread; unexpected failures are 401 (expired session via fetchWithAuth) or 5xx.

Source

Thrown at frontend/src/core/threads/api.ts:79

  }
  return fallback;
}

export async function fetchThreadTokenUsage(
  threadId: string,
): Promise<ThreadTokenUsageResponse | null> {
  const response = await fetchWithAuth(
    `${getBackendBaseURL()}/api/threads/${encodeURIComponent(threadId)}/token-usage`,
    {
      method: "GET",
    },
  );

  if (!response.ok) {
    if (response.status === 403 || response.status === 404) {
      return null;
    }
    throw new Error("Failed to load thread token usage.");
  }

  return (await response.json()) as ThreadTokenUsageResponse;
}

export async function branchThreadFromTurn(
  threadId: string,
  input: BranchThreadFromTurnInput,
): Promise<ThreadBranchResponse> {
  const response = await fetchWithAuth(
    `${getBackendBaseURL()}/api/threads/${encodeURIComponent(threadId)}/branches`,
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        message_id: input.messageId,

View on GitHub (pinned to 1dd6ba1acb)

Solutions

1. Wrap the call and hide the usage widget on failure — usage is auxiliary data
2. On 401, re-authenticate and retry once
3. Apply pending migrations so usage tables match the backend version
4. For 504 on huge threads, open usage on demand rather than on thread load

Example fix

// before
const usage = await fetchThreadTokenUsage(threadId);

// after
const usage = await fetchThreadTokenUsage(threadId).catch(() => null);
if (usage === null) hideUsageWidget();

export function isThreadTokenUsageError(e: unknown): e is Error {
  return e instanceof Error && e.message === 'Failed to load thread token usage.';
}

try {
  return await fetchThreadTokenUsage(threadId);
} catch (e) {
  if (isThreadTokenUsageError(e)) return null; // usage is auxiliary
  throw e;
}

When it happens

Trigger: Loading token usage after session expiry (401); usage aggregation hitting a persistence error (500); very long threads timing out the aggregation query (504).

Common situations: Token/stats panel on legacy threads; backend upgraded with new usage schema but migrations pending; slow storage under load.

Related errors

• Failed to create side conversation.
• Failed to branch conversation.
• Failed to update conversation.
• Failed to compact context.
• Failed to load MCP configuration

AI-assisted analysis of bytedance/deer-flow@1dd6ba1acb (2026-08-14). Data as JSON: /api/errors/21f4007439b6522f. Report an issue: GitHub.