LobeChat places multiple model providers, plugins, and knowledge bases in one interface. With many configuration points, errors are easy to misdiagnose. Most problems are not in the model itself but in one of four layers: a key that is not taking effect, a wrong address or model name, a quota or concurrency ceiling, or a network and cross-origin failure. Classifying first and verifying layer by layer is more effective than repeatedly reinstalling the client.

This article works through 401, 404, 429, and connection failures, then covers streaming output, plugins, and knowledge-base issues. Interface and environment variable names change between versions; follow the documentation for your release. Models and prices are governed by the site's model pricing page, and prices may change.

Note: LobeChat and LobeHub are products and trademarks of their respective owners. This article is a technical troubleshooting guide only and implies no affiliation with the relevant vendors.

1. Record evidence before judging the category

Symptom Common status code or message First judgment Check first
401 authentication error invalid_api_key, empty response Key not recognized Key integrity, owning endpoint, injection method
404 / model not found not_found_error, model_not_found Wrong path or model name Base URL, /v1, model ID
429 Too Many Requests rate_limit_error, insufficient_quota Rate limit or insufficient quota Concurrency, usage, billing
Failed to fetch No status code, browser error Request received no response DNS, proxy, firewall, CORS
5xx server_error, gateway error page Upstream or gateway failure Retry and record the request ID
Plugin or knowledge-base failure Tool-call error, upload failure Missing capability or dependency Function calling, storage, embeddings

Before troubleshooting, record at least: time, version, deployment method (desktop, web, or Docker), status code, response body, and request ID. Without these, you can only guess.

2. 401: the key was not recognized

A 401 means the server rejected the key. Frequent causes include:

  • Spaces, line breaks, or full-width characters were copied along with the key; it looks identical but is not;
  • Interface configuration and deployment environment variables are mixed up, so the request uses a different key than you think;
  • The key was deleted or rotated, or its project was disabled;
  • A key from provider A is sent to provider B's address;
  • A corporate proxy intercepts the request and returns a login page in HTML instead of JSON.

Bypass the client first. Send a minimal request with the same key and the same address:

export ZSQH_API_KEY="sk-your-key"

curl -sS "https://ai.zhongshangqihang.com/v1/chat/completions" \
  -H "Authorization: Bearer $ZSQH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"your-model-id","messages":[{"role":"user","content":"Reply with OK only"}]}' \
  -w "\nHTTP %{http_code}\n"

A 200 response with choices means the key and address are valid; if 401 persists, the problem is in copying, permissions, or a proxy. For Docker deployments, confirm the variables reached the container: docker exec lobe-chat env | grep -i openai, using the container name shown by docker ps. Interface settings belong to the current user and may disappear after switching devices or clearing the cache, so teams should prefer environment variables.

3. 404 and model not found: check the address and the model separately

There are two kinds of 404: the path does not exist, or the model does not exist. The first concerns the URL; the second concerns the model ID.

In LobeChat's proxy address field, some setups accept only the domain while others need /v1, depending on whether the gateway forwards /v1 itself. The test is that /v1 appears exactly once in the final request URL. A common mistake is a host that already ends in /v1 combined with a path that adds it again, producing /v1/v1/chat/completions. The proxy address should point to the API root, not the full /chat/completions path.

model not found is unrelated to the path. Model IDs are case-sensitive and may include version suffixes and vendor prefixes, so copy them from the model pricing page or the console. When managing the list with CUSTOM_MODELS, start with -all,+one-known-working-model as a minimal test, then add others once it passes. Use ASCII commas without spaces. Even when a model appears in the list, confirm that its type and capability switches match reality, or the first call will fail.

A 403 usually means the key is recognized but not allowed to use that model or feature. Do not confuse it with 401 and start swapping keys.

4. CORS, proxies and TLS: pitfalls of direct browser access

When the LobeChat web version sends requests from a browser, the gateway must allow cross-origin requests from its domain. A typical CORS failure shows Access to fetch ... has been blocked by CORS policy in the console while curl works perfectly. There are two remedies: allow the relevant Origin at the gateway, or forward through the server to avoid the browser's cross-origin check.

When LobeChat runs behind Nginx, Caddy, or Cloudflare, the proxy layer must be able to reach the gateway. Do not put the API host and the HTTP proxy in the wrong fields. System proxies, VPNs, and HTTP_PROXY or HTTPS_PROXY inside containers can stack; keep only one layer, and use NO_PROXY to exclude internal addresses.

TLS problems often appear as UNABLE_TO_VERIFY_LEAF_SIGNATURE, frequently with enterprise interception proxies. The correct fix is to install the corporate root certificate. Turning off Node's TLS certificate verification is useful only for temporary diagnosis and reduces security.

Plugin services must also allow the LobeHub Origin. Self-hosted instances should confirm the plugin feature is enabled and the model supports function calling; otherwise plugins fail at execution time.

5. 429: rate limits, concurrency and quota

A 429 usually has two meanings: requests are too fast, or the quota is exhausted. The first often comes with rate_limit_error; the second may be insufficient_quota. The remedies point in opposite directions.

  • Requests too fast: lower concurrency and reduce simultaneously open conversations and clients; long context also amplifies token consumption.
  • Quota exhausted: check gateway usage and billing, top up, or switch keys; retrying alone will not recover.
  • When the response includes Retry-After, wait as instructed; otherwise use exponential backoff with jitter and set a retry cap.
  • When a team shares one key, multiple devices and windows share the same concurrency allowance.

If 429 appears only in long conversations, compress the context or start a new conversation first, then confirm the model's context window. Lowering the "maximum context messages" setting relieves context pressure but is no substitute for usage management.

6. Streaming stops midway: the answer ends halfway

LobeChat returns streamed responses by default. A mid-answer stop is usually not a broken model but SSE buffered by a proxy, an idle connection timeout, or an upstream disconnect during generation. The symptom is a normal first half that ends abruptly, or a permanent "typing" indicator.

Where the version allows, disable streaming first and compare with the same question. If the non-streaming request returns completely, the problem is in the SSE path. A reverse proxy should disable response buffering and extend the read timeout, for example Nginx's proxy_buffering off and proxy_read_timeout; CDNs such as Cloudflare may also buffer event streams. Reasoning models may "think" for a long time before producing text and look stalled, so confirm with a non-streaming request whether there is really no response.

7. Plugin and knowledge-base specific errors

Divide plugin failures into three layers: whether the model supports function calling, whether the plugin gateway is reachable, and whether the plugin service allows cross-origin requests. Self-hosted instances should also confirm the plugin feature is enabled. If a model does not support tool calling, the interface may still open a plugin, but execution fails.

Knowledge bases are a separate dependency stack: PostgreSQL with PGVector for vectors, S3-compatible storage for original files, and a working embedding model. The default embedding model is often an OpenAI model, but your gateway may not offer the same one and needs separate configuration; variable names and value formats follow the current version's documentation.

For upload failures, check the bucket address, credentials, permissions, and CORS. For retrieval failures, check whether the index was built and whether embedding dimensions match. After changing embedding models, the old index usually must be rebuilt. PDF and Word parsing may depend on additional services; if plain text uploads but complex formats fail, investigate in that direction.

8. Logs and evidence collection

  1. Open the browser developer tools Network panel, find the failed request, and record the URL, status code, response body, and headers; remove the key before sharing.
  2. Use docker logs -f lobe-chat to inspect startup errors, migration failures, and connection timeouts.
  3. Use docker exec lobe-chat env to confirm variables exist, watching spelling and quotes.
  4. Run curl or nslookup inside the container to separate container networking, DNS, and the external gateway.
  5. For detailed logs, start with DEBUG=lobe:* and LOG_LEVEL=debug and follow the output.
  6. When filing an issue, include version, deployment method, time, status code, and request ID; "it does not connect" is hard to diagnose.

9. A fixed troubleshooting order

  1. Use curl to reach the gateway directly and confirm whether the key, host, and model are valid.
  2. If curl fails, check DNS, proxy, TLS, firewall, and gateway status.
  3. If curl succeeds but LobeChat fails, check the API type, duplicate /v1, model ID, CORS, and client proxy.
  4. Branch by status code: 401 for the key, 404 for path and model, 429 for usage and concurrency, connection failure for network and certificates.
  5. Change one variable at a time, retest immediately, and record the result.

This order separates client problems from server problems. Most so-called LobeChat errors ultimately come down to one configuration item or one network layer. If you need unified management of keys, usage, and model entry points, you can sign up for the ZSQH AI Gateway; available models and billing methods are listed on the model pricing page.

FAQ

LobeChat reports "Failed to fetch". Is the key wrong?

Not necessarily. The message only means the browser did not receive a valid response. Test the same address with curl first; if curl also fails, check DNS, proxy, firewall, and certificates. If curl succeeds, check CORS, path concatenation, and the client proxy.

Why does curl work while LobeChat returns 401 or a blank response?

Common causes are a mismatch between the interface key and environment variables, spaces copied with the key, a missing or duplicated /v1 in the proxy address, and browser cross-origin blocking. Compare the final request URL and headers item by item.

I added a model to CUSTOM_MODELS but it still does not appear.

Confirm the variable name matches the current version, the commas are ASCII with no spaces, and the container was recreated rather than merely restarted. Start with -all,+one-known-working-model as a minimal test, then add other models.

Will retrying a 429 eventually recover?

Rate-limit 429s may recover after backoff and lower concurrency; quota-related 429s will not recover through retries and require checking billing, usage, or switching keys. Read the error type in the response body before deciding whether to retry.

Is a knowledge-base upload failure the same issue as a chat API error?

Usually not. Chat goes through the chat endpoint, while the knowledge base also depends on the database, vector extension, object storage, and embedding model. Confirm those settings first, then check file formats and parsing services.

Related reading: