Troubleshooting Notes

If you encounter issues while using FastGPT, follow the steps below to troubleshoot and resolve them.

1. Check Version and Upgrade

Many known issues are fixed in newer releases. Before reporting a problem, verify your version first:

• Check version: View the current running version on the FastGPT homepage or in the admin panel.
• Upgrade recommendation: If you are not on the latest version, follow the Upgrade Guide to update to the latest stable release.

2. Troubleshooting Steps

If the issue still exists after upgrading, check in this order:

• Check logs: Review Docker container logs or server logs and locate the specific error stack.
• Clear cache: Clear browser cache or retry in incognito mode.
• Environment check: Ensure MongoDB and PostgreSQL/Milvus connections are healthy and API keys are valid.

3. Prevent Spoofed Client IPs Behind a Reverse Proxy

FastGPT reads the client IP for IP rate limiting, share-link IP allowlists, chat log IP records, and IP geolocation. If your self-hosted FastGPT is behind Nginx, a load balancer, an Ingress controller, or a CDN, make sure clients cannot spoof X-Forwarded-For or X-Real-IP headers.

Recommended setup:

• Overwrite incoming IP headers in Nginx: the last reverse proxy should not pass through a user-supplied X-Forwarded-For header. It should overwrite the header with the real connection source.
• Enable trusted proxy validation in FastGPT: trust forwarded IP headers only when they come from Nginx, the load balancer, or the Ingress controller.
• Restrict direct access to FastGPT: firewall or security group rules should allow only the reverse proxy to access the FastGPT service port.

FastGPT environment variable example:

TRUSTED_PROXY_ENABLE=true
TRUSTED_PROXY_IPS=172.18.0.0/16

TRUSTED_PROXY_IPS should contain the previous-hop proxy IP or CIDR that FastGPT sees directly, such as the Docker subnet for the Nginx container, the Ingress Controller private address, or the load balancer origin address. Do not use a trust-all CIDR such as 0.0.0.0/0 because it would trust every source, and do not add normal client networks to the trusted list.

For a single Nginx layer exposed directly to users, use:

server {
    listen 80;
    server_name fastgpt.example.com;

    location / {
        proxy_pass http://fastgpt:3000;

        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $remote_addr;

        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

If a CDN or load balancer is in front of Nginx, configure Nginx to trust only those upstream egress IPs first. Then forward the restored client IP to FastGPT:

server {
    listen 80;
    server_name fastgpt.example.com;

    # Add only your CDN or load balancer egress IP/CIDR ranges. Do not trust every source.
    set_real_ip_from 10.0.0.0/8;
    set_real_ip_from 172.16.0.0/12;
    real_ip_header X-Forwarded-For;
    real_ip_recursive on;

    location / {
        proxy_pass http://fastgpt:3000;

        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $remote_addr;

        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

If your CDN uses a dedicated real-IP header, use that header in real_ip_header and set set_real_ip_from to the official egress IP ranges published by the CDN. Cloudflare uses CF-Connecting-IP as one example.

After updating Nginx, run:

nginx -t && nginx -s reload

You can verify the setup with spoofed headers:

curl -H 'X-Forwarded-For: 6.6.6.6' -H 'X-Real-IP: 6.6.6.6' https://fastgpt.example.com

If the configuration is correct, FastGPT should still record and validate the real client IP, not the spoofed value 6.6.6.6 from the request.

4. Contact Technical Support

If the issue still cannot be resolved, contact us through:

• Community feedback: Search for similar issues in GitHub Issues or community channels.
• Provide details: When contacting support, include:
  • Full version number currently in use.
  • Detailed issue description with reproduction steps.
  • Related system error logs or screenshots.