# S3 Issues Troubleshooting

> Diagnose object storage connection and upload errors in self-hosted FastGPT

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

## 1. Log shows ERR level "Failed to ensure (external) public/private bucket exists"

### 1.1 Symptom

Startup logs report `Failed to ensure public/private bucket exists` (internal endpoint `STORAGE_S3_ENDPOINT`) or `Failed to ensure external public/private bucket exists` (external endpoint `STORAGE_EXTERNAL_ENDPOINT`), accompanied by `Error: getaddrinfo ENOTFOUND` or `Deserialization error`:

![1.1 Symptom — interface example](https://cdn.jsdelivr.net/gh/labring/fastgpt-img@main/optimized/faq4.png.webp)

### 1.2 Cause

* The hostname in `STORAGE_S3_ENDPOINT` or `STORAGE_EXTERNAL_ENDPOINT` cannot be resolved from the container, or the client uses virtual-hosted bucket addressing (`<bucket>.<endpoint>`) that the storage service does not support.
* The external endpoint points to a reverse proxy or gateway that returns a non-S3 response (such as an HTML 404 page), causing XML deserialization to fail.

### 1.3 Resolution

* Check DNS resolution and network reachability for both `STORAGE_S3_ENDPOINT` and `STORAGE_EXTERNAL_ENDPOINT` from the `fastgpt-app` container.
* For services that use path-style addressing (such as RustFS, MinIO, or IP-based endpoints), set `STORAGE_S3_FORCE_PATH_STYLE` to `true` so the client avoids prepending the bucket name as a subdomain.

***

## 2. Upload conversation file / Dataset file error

### 2.1 Symptom (SignatureDoesNotMatch)

File uploads fail with `SignatureDoesNotMatch`. FastGPT's backend proxies file uploads to object storage, so the Nginx in front of FastGPT does not participate in S3 signing. Inspect the reverse proxy sitting between FastGPT and the object storage service.

### 2.2 Cause

* The reverse proxy in front of the object storage (such as Nginx) does not preserve the original `Host` header (including port), so the host received by object storage differs from the `STORAGE_S3_ENDPOINT` host FastGPT used for signing.

### 2.3 Resolution

* Set `proxy_set_header Host $http_host;` in the Nginx in front of the object storage to preserve the original host and port used to sign the request (Nginx's `$host` variable strips the port).

***
