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
| Symptom | Primary Component & Logs to Inspect | Specialist Guide |
|---|---|---|
| Container fails to start or crash-loops | Inspect fastgpt-app startup logs for MongoDB, PG/Milvus, Redis, and S3 connectivity checks | Troubleshooting Notes · General FAQ |
| Chat or embedding fails with 401/404/429/500 | Run channel connectivity tests under /admin/resources/model and verify AIPROXY_API_ENDPOINT, AIPROXY_API_TOKEN, and channel upstream URLs | Model Troubleshooting |
| File upload fails / broken images / 403 SignatureDoesNotMatch | Verify STORAGE_EXTERNAL_ENDPOINT, STORAGE_S3_ENDPOINT, STORAGE_S3_FORCE_PATH_STYLE, and bucket permissions | S3 Storage Issues · Object Storage Config |
| System tools missing or failing at runtime | Check the fastgpt-plugin container and confirm PLUGIN_BASE_URL and PLUGIN_TOKEN match | Plugin Runtime Configuration |
| Workflow Code Run node unavailable | Check the fastgpt-code-sandbox container and confirm CODE_SANDBOX_URL and CODE_SANDBOX_TOKEN match SANDBOX_TOKEN | Environment Variables · Code Run Node |
| Chat Agent V2 VM sandbox unavailable | Check AGENT_SANDBOX_PROVIDER and the corresponding AGENT_SANDBOX_OPENSANDBOX_* or AGENT_SANDBOX_SEALOS_* variables | OpenSandbox 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:
- Environment baseline: FastGPT image tag,
fastgpt-pluginimage tag, deployment method (Docker Compose, Sealos, Kubernetes), and CPU architecture (x86_64orARM64). - Minimal reproduction steps: Exact UI steps and sample inputs leading to the failure.
- Client and server evidence: The failing request URL, HTTP status, and JSON response from the browser Network tab alongside the corresponding
fastgpt-appcontainer log stack trace.
Last updated