FastGPTFastGPT

S3 Issues Troubleshooting

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

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

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

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.