FastGPTFastGPT

Troubleshooting Methods

Step-by-step diagnostic checklist for container logs, database connectivity, and model calls in FastGPT.

1. Troubleshooting Methods

Search the GitHub issues for a similar problem, or open a new issue. Include the steps to reproduce the problem, relevant logs, and screenshots from your self-hosted deployment.

(1) Get Backend Errors

Run docker compose ps to check the status of every container, then use docker logs to inspect errors from stopped or running services:

# Inspect container statuses and tail recent logs from core services
docker compose ps
docker logs --tail 200 -f fastgpt-app
docker logs --tail 200 -f fastgpt-plugin

(2) Frontend Errors

If the page crashes and asks you to check the console, open your browser developer tools and select Console. Click the file link beside an error to inspect its source location. Include these error details when reporting the issue.


2. Diagnostic Triage Matrix by Component

SymptomPrimary Component & Logs to InspectSpecialist Guide
Container fails to start or crash-loopsInspect fastgpt-app startup logs for MongoDB, PG/Milvus, Redis, and S3 connectivity checksTroubleshooting Notes · General FAQ
Chat or embedding fails with 401/404/429/500Run channel connectivity tests under /admin/resources/model and verify AIPROXY_API_ENDPOINT, AIPROXY_API_TOKEN, and channel upstream URLsModel Troubleshooting
File upload fails / broken images / 403 SignatureDoesNotMatchVerify STORAGE_EXTERNAL_ENDPOINT, STORAGE_S3_ENDPOINT, STORAGE_S3_FORCE_PATH_STYLE, and bucket permissionsS3 Storage Issues · Object Storage Config
System tools missing or failing at runtimeCheck the fastgpt-plugin container and confirm PLUGIN_BASE_URL and PLUGIN_TOKEN matchPlugin Runtime Configuration
Workflow Code Run node unavailableCheck the fastgpt-code-sandbox container and confirm CODE_SANDBOX_URL and CODE_SANDBOX_TOKEN match SANDBOX_TOKENEnvironment Variables · Code Run Node
Chat Agent V2 VM sandbox unavailableCheck AGENT_SANDBOX_PROVIDER and the corresponding AGENT_SANDBOX_OPENSANDBOX_* or AGENT_SANDBOX_SEALOS_* variablesOpenSandbox Configuration · Sealos Devbox Configuration

3. Issue Reporting Checklist (Sanitized)

When filing a GitHub issue, remove all API keys, database passwords, and rootkey values, and include:

  1. Environment baseline: FastGPT image tag, fastgpt-plugin image tag, deployment method (Docker Compose, Sealos, Kubernetes), and CPU architecture (x86_64 or ARM64).
  2. Minimal reproduction steps: Exact UI steps and sample inputs leading to the failure.
  3. Client and server evidence: The failing request URL, HTTP status, and JSON response from the browser Network tab alongside the corresponding fastgpt-app container log stack trace.
Edit on GitHub

Last updated

On this page

Put your business knowledge to work with AI

Import company documents and build accurate, reliable, traceable AI answers.