Private Deployment FAQ

FastGPT private deployment common issues

1. Error Troubleshooting

Check Issues first, or create a new one. For private deployment errors, provide detailed steps, logs, and screenshots — otherwise it's very difficult to diagnose.

Backend Errors

  1. Run docker ps -a to check all container statuses. Verify everything is running. If not, use docker logs <container_name> to view logs.
  2. If containers are running normally, use docker logs <container_name> to check for error logs.

Frontend Errors

When the frontend crashes, the page will display an error prompting you to check console logs. Open the browser console and check the console tab. Click the log hyperlinks to see the specific error file — provide these details for troubleshooting.

OneAPI Errors

Errors with requestId are from OneAPI, usually caused by model API issues. See Common OneAPI Errors

2. General Issues

Frontend Page Crash

  1. 90% of cases: incorrect model configuration. Ensure each model type has at least one enabled. Check if object parameters are abnormal (arrays and objects) — if empty, try providing an empty array or object.
  2. Browser compatibility: the project uses advanced syntax that may not work in older browsers. Provide specific steps and console errors in an issue.
  3. Disable browser translation — it can cause page crashes.

Does Sealos deployment have fewer limitations than local deployment?

This is the index model's length limit — it's the same regardless of deployment method. Different index models have different configurations, which you can modify in the admin panel.

How to Mount Mini Program Config Files

Mount the verification file to: /app/projects/app/public/xxxx.txt

Then restart. For example:

Database Port 3306 Already in Use

Change the port mapping to something like 3307, e.g., 3307:3306.

Local Deployment Limitations

See details at https://fael3z0zfze.feishu.cn/wiki/OFpAw8XzAi36Guk8dfucrCKUnjg.

Can It Run Fully Offline?

Yes. You'll need vector models and LLM models ready.

Other Models Can't Do Question Classification / Content Extraction

  1. Check logs. If you see "JSON invalid" or "not support tool", the model doesn't support tool/function calling. Set toolChoice=false and functionCall=false to fall back to prompt mode. Built-in prompts are only tested with commercial model APIs. Question classification mostly works; content extraction is less reliable.
  2. If configured correctly with no error logs, the prompts may not suit the model. Customize via customCQPrompt.

Page Crash

  1. Disable browser translation.
  2. Check if the config file loaded properly — missing system info causes null pointer errors.
  • 95% of cases: incorrect config file, showing "xxx undefined"
  • "URI malformed" error: report the specific operation and page in an issue — caused by special character encoding errors.
  1. Some API compatibility issues (rare)

Slow Response After Enabling Content Completion

  1. Content completion requires an additional AI generation round.
  2. Performs 3–5 query rounds — insufficient database performance will cause noticeable slowdowns.

Page Works Fine, API Returns Errors

The page uses stream=true mode, so the API also needs stream=true for testing. Some model APIs (especially domestic ones) have poor non-stream compatibility. Same as above — test with curl.

Knowledge Base Indexing Has No Progress / Very Slow

Check error logs first. Possible scenarios:

  1. Can chat but no indexing progress: vector model (vectorModels) not configured
  2. Can't chat or index: API call failed — may not be connected to OneAPI or OpenAI
  3. Has progress but very slow: API key issue. OpenAI free accounts have very limited rate limits (3 or 60 requests/minute, 200/day).

Connection Error

Network issue. Servers in China can't reach OpenAI directly — verify your AI model connection.

Or FastGPT can't reach OneAPI (not on the same network).

Modified vectorModels But No Effect

  1. Restart the container and confirm the model config loaded (check logs or the new knowledge base creation page).
  2. Refresh the browser.
  3. For existing knowledge bases, delete and recreate them. The vector model is bound at creation time and won't update dynamically.

3. Common OneAPI Errors

Errors with requestId are from OneAPI.

insufficient_user_quota user quota is not enough

OneAPI account balance insufficient. The default root user only has $200 — increase it manually.

Path: Open OneAPI -> Users -> Edit root user -> Increase remaining balance

xxx Channel Not Found

The model in FastGPT's config must match a model in OneAPI channels. Check:

  1. The model channel isn't configured in OneAPI, or is disabled.
  2. FastGPT config has models not configured in OneAPI. Don't add models to config that OneAPI doesn't have.
  3. Created a knowledge base with an old vector model, then updated the vector model. Delete old knowledge bases and recreate.

If OneAPI doesn't have the model configured, don't add it to config.json either.

Model Test Click Fails

OneAPI only tests the first model in a channel, and only chat models. Vector models can't be auto-tested — send manual requests. View test command examples

get request url failed: Post "https://xxx" dial tcp: xxxx

OneAPI can't reach the model — check network configuration.

Incorrect API key provided: sk-xxxx.You can find your api Key at xxx

OneAPI API Key configured incorrectly. Modify the OPENAI_API_KEY environment variable and restart (docker-compose down then docker-compose up -d).

Use exec to enter the container, then env to verify environment variables.

bad_response_status_code bad response status code 503

  1. Model service unavailable
  2. Incompatible model API parameters (temperature, max token, etc.)
  3. ...

Tiktoken Download Failed

OneAPI downloads a tiktoken dependency at startup. Network failure causes startup failure. See OneAPI Offline Deployment.

4. Common Model Issues

How to Check Model Availability

  1. For self-hosted models, confirm the deployment is working.
  2. Use CURL to directly test the upstream model (both cloud and private models).
  3. Use CURL to test through OneAPI.
  4. Test the model in FastGPT.

Here are some test CURL examples:

curl https://api.openai.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {
        "role": "system",
        "content": "You are a helpful assistant."
      },
      {
        "role": "user",
        "content": "Hello!"
      }
    ]
  }'
curl https://api.openai.com/v1/embeddings \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "The food was delicious and the waiter...",
    "model": "text-embedding-ada-002",
    "encoding_format": "float"
  }'
curl --location --request POST 'https://xxxx.com/api/v1/rerank' \
--header 'Authorization: Bearer {{ACCESS_TOKEN}}' \
--header 'Content-Type: application/json' \
--data-raw '{
  "model": "bge-rerank-m3",
  "query": "导演是谁",
  "documents": [
    "你是谁？\n我是电影《铃芽之旅》助手"
  ]
}'
curl https://api.openai.com/v1/audio/speech \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tts-1",
    "input": "The quick brown fox jumped over the lazy dog.",
    "voice": "alloy"
  }' \
  --output speech.mp3
curl https://api.openai.com/v1/audio/transcriptions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F file="@/path/to/file/audio.mp3" \
  -F model="whisper-1"

Error — Model Response Empty / Model Error

This occurs when OneAPI ends the stream request without returning any content.

Version 4.8.10 added error logging — the actual request body is printed in logs on error. Copy it and use curl to test against OneAPI.

Since OneAPI can't properly catch errors in stream mode, you can set stream=false to get precise error messages.

Possible causes:

  1. Content moderation triggered
  2. Unsupported model parameters: keep only messages and essential parameters, remove the rest
  3. Parameters don't meet model requirements: e.g., some models don't support temperature=0, some don't support two decimal places, max_tokens exceeded, context too long, etc.
  4. Model deployment issues with stream mode incompatibility

Test example — copy the request body from error logs:

curl --location --request POST 'https://api.openai.com/v1/chat/completions' \
--header 'Authorization: Bearer sk-xxxx' \
--header 'Content-Type: application/json' \
--data-raw '{
  "model": "xxx",
  "temperature": 0.01,
  "max_tokens": 1000,
  "stream": true,
  "messages": [
    {
      "role": "user",
      "content": " 你是饿"
    }
  ]
}'

How to Test if a Model Supports Tool Calling

Both the model provider and OneAPI must support tool calling. Test as follows:

1. Send a first-round stream mode tool call request to OneAPI via curl.
curl --location --request POST 'https://oneapi.xxx/v1/chat/completions' \
--header 'Authorization: Bearer sk-xxxx' \
--header 'Content-Type: application/json' \
--data-raw '{
  "model": "gpt-5",
  "temperature": 0.01,
  "max_tokens": 8000,
  "stream": true,
  "messages": [
    {
      "role": "user",
      "content": "几点了"
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "hCVbIY",
        "description": "获取用户当前时区的时间。",
        "parameters": {
          "type": "object",
          "properties": {},
          "required": []
        }
      }
    }
  ],
  "tool_choice": "auto"
}'
2. Check the Response

If tool calling works, the response includes tool_calls parameters.

{
    "id": "chatcmpl-A7kwo1rZ3OHYSeIFgfWYxu8X2koN3",
    "object": "chat.completion.chunk",
    "created": 1726412126,
    "model": "gpt-5",
    "system_fingerprint": "fp_483d39d857",
    "choices": [
        {
            "index": 0,
            "id": "call_0n24eiFk8OUyIyrdEbLdirU7",
            "type": "function",
            "function": {
              "name": "mEYIcFl84rYC",
              "arguments": ""
            }
          }
        ],
        "refusal": null
      },
      "logprobs": null,
      "finish_reason": null
    }
  ],
  "usage": null
}
3. Send a second-round stream mode tool call request to OneAPI via curl.

The second round sends tool results back to the model and returns the model's response.

curl --location --request POST 'https://oneapi.xxxx/v1/chat/completions' \
--header 'Authorization: Bearer sk-xxx' \
--header 'Content-Type: application/json' \
--data-raw '{
  "model": "gpt-5",
  "temperature": 0.01,
  "max_tokens": 8000,
  "stream": true,
  "messages": [
    {
      "role": "user",
      "content": "几点了"
    },
    {
      "role": "assistant",
      "tool_calls": [
        {
          "id": "kDia9S19c4RO",
          "type": "function",
          "function": {
            "name": "hCVbIY",
            "arguments": "{}"
          }
        }
      ]
    },
    {
      "tool_call_id": "kDia9S19c4RO",
      "role": "tool",
      "name": "hCVbIY",
      "content": "{\n  \"time\": \"2024-09-14 22:59:21 Sunday\"\n}"
    }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "hCVbIY",
        "description": "获取用户当前时区的时间。",
        "parameters": {
          "type": "object",
          "properties": {},
          "required": []
        }
      }
    }
  ],
  "tool_choice": "auto"
}'

Vector Retrieval Score Greater Than 1

Caused by the model not being normalized. Only normalized models are currently supported.

Edit on GitHub

File Updated

Integrate SigNoz Service Monitoring

FastGPT integration with SigNoz service monitoring

Upgrade Guide

FastGPT version upgrade guide