docs(getting-started): fix '502 Bad Gateway' error in the getting sta…

[hachi029]

…rted tutorial

Description

When following the getting-started guide, a 502 Bad Gateway response is returned.

root@28d6b762434f:/workspace# curl "http://127.0.0.1:9080/ip

<title>502 Bad Gateway</title>

502 Bad Gateway

---

openresty

Powered by APISIX.

Based on my validation, I found that the pass_host: "node" configuration must be added to the route to make APISIX send right Host header to httpbin.org to get a correct response (instead of 502 errors).

root@28d6b762434f:/workspace# curl -m 5 -v "http://httpbin.org/ip"
* Connected to httpbin.org (100.29.246.92) port 80
> GET /ip HTTP/1.1
> Host: httpbin.org
> User-Agent: curl/8.5.0
> Accept: */*
>
< HTTP/1.1 200 OK
< Connection: close
< Content-Length: 34
< Access-Control-Allow-Credentials: true
< Access-Control-Allow-Origin: *
< Content-Type: application/json
< Date: Thu, 27 Nov 2025 04:33:11 GMT
< Server: gunicorn/19.9.0
<
{
"origin": "101.x.x.177"
}

root@28d6b762434f:/workspace# curl -m 5 -v "http://httpbin.org/ip" -H "Host: 127.0.0.1:9080"
* Connected to httpbin.org (3.219.87.227) port 80
> GET /ip HTTP/1.1
> Host: 127.0.0.1:9080
> User-Agent: curl/8.5.0
> Accept: */*
>
* Operation timed out after 5002 milliseconds with 0 bytes received
curl: (28) Operation timed out after 5002 milliseconds with 0 bytes received

root@28d6b762434f:/workspace# curl -m 5 -v "http://httpbin.org/ip" -H "Host: 127.0.0.1:9080"
* Connected to httpbin.org (100.29.246.92) port 80
> GET /ip HTTP/1.1
> Host: 127.0.0.1:9080
> User-Agent: curl/8.5.0
> Accept: */*

* Empty reply from server
* Closing connection
curl: (52) Empty reply from server

Which issue(s) this PR fixes:

Checklist

• I have explained the need for this PR and the problem it solves
• I have explained the changes or the new features added to this PR
• I have added tests corresponding to this change
• I have updated the documentation to reflect this change
• I have verified that this change is backward compatible (If not, please discuss on the APISIX mailing list first)

[Baoyuantop]

Hi @hachi029, I didn't have the problem you described after trying it locally.

[hachi029]

I’ve also verified this on other computers and encountered the same issue：

1. OK：

~ curl -v httpbin.org/ip
* Host httpbin.org:80 was resolved.
* IPv6: (none)
* IPv4: 52.6.181.49, 54.227.38.221, 3.219.87.227, 3.232.74.21, 52.44.182.178, 100.29.246.92
* Trying 52.6.181.49:80...
* Connected to httpbin.org (52.6.181.49) port 80
> GET /ip HTTP/1.1
> Host: httpbin.org
> User-Agent: curl/8.7.1
> Accept: */*

* Request completely sent off
< HTTP/1.1 200 OK
< Date: Thu, 27 Nov 2025 07:17:22 GMT
< Content-Type: application/json
< Content-Length: 33
< Connection: keep-alive
< Server: gunicorn/19.9.0
< Access-Control-Allow-Origin: *
< Access-Control-Allow-Credentials: true
<
{
"origin": "223.x.x.x"
}
* Connection #0 to host httpbin.org left intact

2. failed with Header Host: 127.0.0.1:8090 just like APISIX does in the getting stated tutorial.

➜ ~ curl -v httpbin.org/ip -H "Host: 127.0.0.1:8090"
* Host httpbin.org:80 was resolved.
* IPv6: (none)
* IPv4: 54.227.38.221, 3.219.87.227, 3.232.74.21, 52.44.182.178, 100.29.246.92, 52.6.181.49
* Trying 54.227.38.221:80...
* Connected to httpbin.org (54.227.38.221) port 80
> GET /ip HTTP/1.1
> Host: 127.0.0.1:8090
> User-Agent: curl/8.7.1
> Accept: */*

* Request completely sent off
* Recv failure: Connection reset by peer
* Closing connection
curl: (56) Recv failure: Connection reset by peer

[hachi029]

It's ok on my volcengine ECS, but not on my personal computer.