# Troubleshooting Methods

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

Source: https://doc.fastgpt.io/self-host/troubleshooting/methods
Last Updated: 2026-11-12

## 1. Troubleshooting Methods

Search the [GitHub issues](https://github.com/labring/FastGPT/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:

```bash
# 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](https://doc.fastgpt.io/self-host/troubleshooting/attention) · [General FAQ](https://doc.fastgpt.io/self-host/troubleshooting/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](https://doc.fastgpt.io/self-host/troubleshooting/model-errors)                                                                                                 |
| **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](https://doc.fastgpt.io/self-host/troubleshooting/s3-issues) · [Object Storage Config](https://doc.fastgpt.io/self-host/config/object-storage)                      |
| **System tools missing or failing at runtime**                    | Check the `fastgpt-plugin` container and confirm `PLUGIN_BASE_URL` and `PLUGIN_TOKEN` match                                                     | [Plugin Runtime Configuration](https://doc.fastgpt.io/plugin/runtime)                                                                                                                  |
| **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](https://doc.fastgpt.io/self-host/config/env) · [Code Run Node](https://doc.fastgpt.io/guide/build/workflow/nodes/sandbox-v2)                                   |
| **Chat Agent V2 VM sandbox unavailable**                          | Check `AGENT_SANDBOX_PROVIDER` and the corresponding `AGENT_SANDBOX_OPENSANDBOX_*` or `AGENT_SANDBOX_SEALOS_*` variables                        | [OpenSandbox Configuration](https://doc.fastgpt.io/self-host/config/sandbox/opensandbox) · [Sealos Devbox Configuration](https://doc.fastgpt.io/self-host/config/sandbox/sealosdevbox) |

## 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.
