https://adminsforum.com/ Thu, 15 Oct 2026 07:04:49 +0000 MyBB https://adminsforum.com/Thread-guide-fix-python-and-flask-502-bad-gateway-in-aapanel Wed, 14 Oct 2026 15:10:30 +0800 DEV]]> https://adminsforum.com/Thread-guide-fix-python-and-flask-502-bad-gateway-in-aapanel A 502 Bad Gateway response from Nginx usually means it could not get a valid response from the application behind it. For a Flask project, diagnose Gunicorn and the local port before changing DNS or opening firewall ports.

Tested lab: aaPanel Free 8.0.7 on Ubuntu 22.04.5. Project af_flask_lab uses Gunicorn on 127.0.0.1:3200 and Nginx serves flask.adminslab.com. We deliberately stopped this disposable project, reproduced public HTTP 502, then started it and recovered HTTP 200. No production website was stopped.


  python-502-workflow-20261014.jpg (Size: 93.17 KB / Downloads: 6)
Diagnostic workflow diagram: check the app before changing its proxy configuration.

1. Separate the error from a certificate problem
Open the hostname and record the actual response. A page saying 502 Bad Gateway is different from a TLS certificate warning, DNS failure or application-generated 500. Do not disable certificate validation to make the test appear successful.

2. Test the local application port
From the VPS terminal, replacing 3200 with your actual port:

Code:Copy

curl -i http://127.0.0.1:3200/ ss -lntp | grep ':3200'

• Connection refused/no listener: the app is stopped, failed at startup or bound to another port.
  
• HTTP 200 locally but 502 publicly: inspect Nginx mapping and compare its upstream with the working listener.
  
• Application 500 locally: investigate the application traceback, configuration and database dependencies.
  

Do not expose the Gunicorn port to the Internet as a workaround. Nginx can reach a localhost listener without a public firewall rule for 3200.

3. Check aaPanel project status and logs
Open Website → Python Project, click the project name, then open Project logs. In our lab the log is:

Code:Copy

/www/wwwlogs/python/af_flask_lab/error.log

Read the newest startup messages. Look for ModuleNotFoundError, an incorrect callable, Permission denied, Address already in use or a missing environment executable. These need different fixes.

For our app, Project information uses:

• Environment: af_python_lab
  
• Path: /www/wwwroot/af-flask-lab
  
• Startup way: Command Startup
  
• User: www
  
• Command: gunicorn --workers 1 --bind 127.0.0.1:3200 app:app
  

The first app in app:app means app.py; the second means the Flask object named app. Match your own module and object instead of copying this blindly.

4. Confirm the right packages are installed
Use the selected environment's Python executable, not an unrelated system pip:

Code:Copy

/www/server/pyporject_evn/af_python_lab/bin/python -m pip show Flask gunicorn /www/server/pyporject_evn/af_python_lab/bin/python -m pip check

The path above is the actual directory name used by this lab's aaPanel version. Use your environment path if different. Install missing application packages from its reviewed requirements file, then retry startup. Do not solve package errors by installing everything globally as root.

5. Compare the Nginx mapping
In the project window, open Mapping. Confirm external network mapping is enabled and its detected port matches the actual Gunicorn listener. Ensure the domain is attached to this project in Domain Manager.

For our HTTP Gunicorn app, Nginx routes to:

Code:Copy

proxy_pass http://127.0.0.1:3200;

A wrong port or using https for a plain-HTTP upstream can prevent Nginx from connecting. If you edit Nginx configuration, back it up, validate it and reload only after validation succeeds. Avoid replacing the entire configuration with an unrelated example.

6. Start the app and verify both paths
Use the project's Start control after fixing the cause. Wait for the process to initialize, then test localhost and the public hostname again. In our controlled lab test:

• Before stopping: public HTTPS returned HTTP 200 and AdminsForum Flask lab.
  
• After the native stop command: public HTTPS returned HTTP 502.
  
• After the native start command: public HTTPS returned HTTP 200 with the expected Flask response.
  

This proves a stopped upstream can produce this symptom. It does not prove every 502 has that cause.

If the problem occurs after reboot
Check the native Startup option and allow for its advertised 120-second daemon interval. See Python startup and reboot recovery. That guide also documents a lab-version issue where saving project settings removed the SSL listener; verify HTTPS separately after settings changes.

When asking for support
Share the aaPanel version, startup method, sanitized command, local HTTP result, mapping port and relevant recent log lines. Remove passwords, tokens, cookies, private keys and database connection secrets before posting.

AdminsForum lab-tested troubleshooting guide. Illustration is a workflow diagram, not a screenshot of an error page.]]> A 502 Bad Gateway response from Nginx usually means it could not get a valid response from the application behind it. For a Flask project, diagnose Gunicorn and the local port before changing DNS or opening firewall ports.

Tested lab: aaPanel Free 8.0.7 on Ubuntu 22.04.5. Project af_flask_lab uses Gunicorn on 127.0.0.1:3200 and Nginx serves flask.adminslab.com. We deliberately stopped this disposable project, reproduced public HTTP 502, then started it and recovered HTTP 200. No production website was stopped.


  python-502-workflow-20261014.jpg (Size: 93.17 KB / Downloads: 6)
Diagnostic workflow diagram: check the app before changing its proxy configuration.

1. Separate the error from a certificate problem
Open the hostname and record the actual response. A page saying 502 Bad Gateway is different from a TLS certificate warning, DNS failure or application-generated 500. Do not disable certificate validation to make the test appear successful.

2. Test the local application port
From the VPS terminal, replacing 3200 with your actual port:

Code:Copy

curl -i http://127.0.0.1:3200/ ss -lntp | grep ':3200'

• Connection refused/no listener: the app is stopped, failed at startup or bound to another port.
  
• HTTP 200 locally but 502 publicly: inspect Nginx mapping and compare its upstream with the working listener.
  
• Application 500 locally: investigate the application traceback, configuration and database dependencies.
  

Do not expose the Gunicorn port to the Internet as a workaround. Nginx can reach a localhost listener without a public firewall rule for 3200.

3. Check aaPanel project status and logs
Open Website → Python Project, click the project name, then open Project logs. In our lab the log is:

Code:Copy

/www/wwwlogs/python/af_flask_lab/error.log

Read the newest startup messages. Look for ModuleNotFoundError, an incorrect callable, Permission denied, Address already in use or a missing environment executable. These need different fixes.

For our app, Project information uses:

• Environment: af_python_lab
  
• Path: /www/wwwroot/af-flask-lab
  
• Startup way: Command Startup
  
• User: www
  
• Command: gunicorn --workers 1 --bind 127.0.0.1:3200 app:app
  

The first app in app:app means app.py; the second means the Flask object named app. Match your own module and object instead of copying this blindly.

4. Confirm the right packages are installed
Use the selected environment's Python executable, not an unrelated system pip:

Code:Copy

/www/server/pyporject_evn/af_python_lab/bin/python -m pip show Flask gunicorn /www/server/pyporject_evn/af_python_lab/bin/python -m pip check

The path above is the actual directory name used by this lab's aaPanel version. Use your environment path if different. Install missing application packages from its reviewed requirements file, then retry startup. Do not solve package errors by installing everything globally as root.

5. Compare the Nginx mapping
In the project window, open Mapping. Confirm external network mapping is enabled and its detected port matches the actual Gunicorn listener. Ensure the domain is attached to this project in Domain Manager.

For our HTTP Gunicorn app, Nginx routes to:

Code:Copy

proxy_pass http://127.0.0.1:3200;

A wrong port or using https for a plain-HTTP upstream can prevent Nginx from connecting. If you edit Nginx configuration, back it up, validate it and reload only after validation succeeds. Avoid replacing the entire configuration with an unrelated example.

6. Start the app and verify both paths
Use the project's Start control after fixing the cause. Wait for the process to initialize, then test localhost and the public hostname again. In our controlled lab test:

• Before stopping: public HTTPS returned HTTP 200 and AdminsForum Flask lab.
  
• After the native stop command: public HTTPS returned HTTP 502.
  
• After the native start command: public HTTPS returned HTTP 200 with the expected Flask response.
  

This proves a stopped upstream can produce this symptom. It does not prove every 502 has that cause.

If the problem occurs after reboot
Check the native Startup option and allow for its advertised 120-second daemon interval. See Python startup and reboot recovery. That guide also documents a lab-version issue where saving project settings removed the SSL listener; verify HTTPS separately after settings changes.

When asking for support
Share the aaPanel version, startup method, sanitized command, local HTTP result, mapping port and relevant recent log lines. Remove passwords, tokens, cookies, private keys and database connection secrets before posting.

AdminsForum lab-tested troubleshooting guide. Illustration is a workflow diagram, not a screenshot of an error page.]]> https://adminsforum.com/Thread-guide-fix-python-venv-and-ensurepip-errors-in-aapanel-on-ubuntu Wed, 14 Oct 2026 14:17:07 +0800 DEV]]> https://adminsforum.com/Thread-guide-fix-python-venv-and-ensurepip-errors-in-aapanel-on-ubuntu If aaPanel reports that Python virtual-environment creation returned non-zero exit status 1, the popup alone does not identify the cause. In our Ubuntu lab, the selected system Python lacked ensurepip support because its venv package was not installed. Installing the matching Ubuntu package fixed the creation failure.


  python-venv-error-20261014.jpg (Size: 106.4 KB / Downloads: 4)
The actual aaPanel virtual-environment creation failure in the lab.

Tested: Ubuntu 22.04.5 LTS, aaPanel Free 8.0.7, selected interpreter /usr/bin/python3.10. Tested on 14 October 2026. The package and paths below apply to this specific combination; do not assume every exit-status-1 error has the same cause.

1. Record the failed command
The popup showed that aaPanel attempted:

Code:Copy

/usr/bin/python3.10 -m venv /www/server/pyporject_evn/af_python_lab

Record the interpreter and target directory. Do not delete a working environment to investigate an unrelated creation error.

2. Read the underlying error
Over SSH, repeat the creation command only for the newly failed lab target, or choose a fresh unused diagnostic directory. In our test, the error explained that ensurepip was not available and recommended python3.10-venv.

Use the exact selected interpreter. Running a different python command could test another Python installation and hide the problem.

3. Check the matching package
On our Ubuntu server:

Code:Copy

apt-cache policy python3.10-venv

It showed Installed: (none), with a candidate available from Ubuntu's repository. Confirm the selected Python version and repository source before installing a package. Other distributions and vendor-managed interpreters have different prerequisite workflows.

4. Install venv support
As an administrator:

Code:Copy

sudo apt-get install python3.10-venv

Our package manager installed python3.10-venv and its pip/setuptools wheel prerequisites. No unrelated packages were removed. Keep package-manager errors if installation fails; do not continue as if the prerequisite is ready.

5. Retry the aaPanel form
Return to Website → Python Project → Python Environment. Dismiss the error popup, then retry the new environment's creation form. We used the same selected system interpreter and environment name. It succeeded and appeared in the environment list.

A failed attempt may leave a partial directory. In our lab the retry completed it successfully. Do not recursively delete a directory unless you have verified that it belongs only to the failed disposable attempt and no project uses it.

6. Verify the result

Code:Copy

/www/server/pyporject_evn/af_python_lab/bin/python --version /www/server/pyporject_evn/af_python_lab/bin/python -m pip --version /www/server/pyporject_evn/af_python_lab/bin/python -c 'import sys; print(sys.prefix != sys.base_prefix)'

The lab returned Python 3.10.12, pip 22.0.2 inside the new environment and True for the isolation check. Substitute the actual interpreter path from your environment.

If the error continues
Check available disk space, parent-directory permissions, the selected interpreter and the complete command error. Missing ensurepip was our verified cause, not a universal diagnosis. Avoid changing aaPanel's own environment or reinstalling the whole panel before identifying the failure.

Related guide: Create a Python virtual environment in aaPanel.]]> If aaPanel reports that Python virtual-environment creation returned non-zero exit status 1, the popup alone does not identify the cause. In our Ubuntu lab, the selected system Python lacked ensurepip support because its venv package was not installed. Installing the matching Ubuntu package fixed the creation failure.


  python-venv-error-20261014.jpg (Size: 106.4 KB / Downloads: 4)
The actual aaPanel virtual-environment creation failure in the lab.

Tested: Ubuntu 22.04.5 LTS, aaPanel Free 8.0.7, selected interpreter /usr/bin/python3.10. Tested on 14 October 2026. The package and paths below apply to this specific combination; do not assume every exit-status-1 error has the same cause.

1. Record the failed command
The popup showed that aaPanel attempted:

Code:Copy

/usr/bin/python3.10 -m venv /www/server/pyporject_evn/af_python_lab

Record the interpreter and target directory. Do not delete a working environment to investigate an unrelated creation error.

2. Read the underlying error
Over SSH, repeat the creation command only for the newly failed lab target, or choose a fresh unused diagnostic directory. In our test, the error explained that ensurepip was not available and recommended python3.10-venv.

Use the exact selected interpreter. Running a different python command could test another Python installation and hide the problem.

3. Check the matching package
On our Ubuntu server:

Code:Copy

apt-cache policy python3.10-venv

It showed Installed: (none), with a candidate available from Ubuntu's repository. Confirm the selected Python version and repository source before installing a package. Other distributions and vendor-managed interpreters have different prerequisite workflows.

4. Install venv support
As an administrator:

Code:Copy

sudo apt-get install python3.10-venv

Our package manager installed python3.10-venv and its pip/setuptools wheel prerequisites. No unrelated packages were removed. Keep package-manager errors if installation fails; do not continue as if the prerequisite is ready.

5. Retry the aaPanel form
Return to Website → Python Project → Python Environment. Dismiss the error popup, then retry the new environment's creation form. We used the same selected system interpreter and environment name. It succeeded and appeared in the environment list.

A failed attempt may leave a partial directory. In our lab the retry completed it successfully. Do not recursively delete a directory unless you have verified that it belongs only to the failed disposable attempt and no project uses it.

6. Verify the result

Code:Copy

/www/server/pyporject_evn/af_python_lab/bin/python --version /www/server/pyporject_evn/af_python_lab/bin/python -m pip --version /www/server/pyporject_evn/af_python_lab/bin/python -c 'import sys; print(sys.prefix != sys.base_prefix)'

The lab returned Python 3.10.12, pip 22.0.2 inside the new environment and True for the isolation check. Substitute the actual interpreter path from your environment.

If the error continues
Check available disk space, parent-directory permissions, the selected interpreter and the complete command error. Missing ensurepip was our verified cause, not a universal diagnosis. Avoid changing aaPanel's own environment or reinstalling the whole panel before identifying the failure.

Related guide: Create a Python virtual environment in aaPanel.]]> https://adminsforum.com/Thread-guide-fix-node-js-502-bad-gateway-in-aapanel-check-ports-mapping-and-logs Wed, 14 Oct 2026 10:52:21 +0800 DEV]]> https://adminsforum.com/Thread-guide-fix-node-js-502-bad-gateway-in-aapanel-check-ports-mapping-and-logs For a Node.js website behind aaPanel's Nginx mapping, a 502 Bad Gateway often means the web server could not get a usable response from the application. Start by testing the app locally, then compare its listening port with the mapping. Reinstalling Node.js or disabling the firewall is not a useful first diagnostic step.

Tested lab: aaPanel Free 8.0.7, Node.js 24.21.0, project afnodelab, app at 127.0.0.1:3100, domain node.adminslab.com. On 14 October 2026 we stopped only this sample app using aaPanel's native project controls, observed HTTPS 502, started it again and observed HTTPS 200. The app is restored and running.

1. Identify which layer fails
Run these checks over SSH on the VPS:

Code:Copy

curl -i http://127.0.0.1:3100/ curl -I https://node.adminslab.com/

Replace the sample port and domain with yours. The local request reaches the Node application directly. The domain request goes through DNS, TLS and the web server. Compare the results:

• Local connection refused + public 502: Check whether the app is running and whether the port is correct.
  
• Local 200 + public 502: Check the mapping's upstream address and port, then the website error log.
  
• Both return 200: The fault may have cleared. Check logs and monitoring before changing settings.
  
• TLS validation fails: Investigate the certificate separately; a certificate error is different from an HTTP 502 response.
  

2. Find the actual listening port
For our sample:

Code:Copy

ss -ltnp | grep ':3100'

The expected listener is 127.0.0.1:3100. We also tested 127.0.0.1:3101, where no app was listening, and curl returned connection refused. This demonstrates why guessing an upstream port is unreliable. We did not deliberately change the live mapping to that incorrect port.

If your app listens on another port, use that port in the local check and the aaPanel project settings. For an app behind a local reverse proxy, a localhost-only listener is appropriate. It does not need its application port opened publicly just to be reached by Nginx on the same machine.

3. Check project configuration
Open Website → Node.js Project, click the project name and inspect Project config. Compare the directory, start command, selected runtime, run user and port against the application's own configuration.


  node-app-config-20261014.jpg (Size: 191.89 KB / Downloads: 4)
Reference screenshot from the sample deployment: project port 3100, www user and Node.js runtime.

Changing the Project Port field does not rewrite a hard-coded port in server.js. The two must agree. Also check that the selected directory contains the expected package.json and startup file. Our sample uses start → node server.js and runs as www.

4. Read Project log before restarting
Open Project log. Look for the latest startup message and any error that precedes it.


  node-app-log-20261014.jpg (Size: 161.85 KB / Downloads: 3)
Reference startup log from the sample deployment shows the app listening on localhost:3100.

• Module not found: Check the application's dependency installation and selected runtime.
  
• Permission denied: Check the run user's access to the app directory and required resources.
  
• Address already in use: Identify the existing listener; do not start duplicate copies.
  
• App starts then exits: Read the exit error and check required environment variables or external services.
  

Do not switch the app to root or use permissions 777 to hide an access problem. Fix the specific missing permission instead.

5. Check the mapping
In Domain Manager, confirm the intended hostname is present. In Mapping, confirm mapping is enabled. Check the relevant web-server configuration read-only before making changes.

Our generated configuration contains:

Code:Copy

server_name node.adminslab.com; proxy_pass http://127.0.0.1:3100;

That upstream matches the app's listener. Configuration filenames differ between projects and versions; inspect the relevant site's configuration rather than editing an unrelated file. Prefer the panel's controls for changes, and validate the web-server configuration before reloading it.

6. Restore a stopped application
Use Service status → Start for a stopped project, or Restart when appropriate for the selected app. Confirm the action and wait for startup to finish. Repeat the local and domain checks; a Running label alone does not prove the application returns the expected page.

Our controlled test produced:

Code:Copy

Native project stop: Stopped successfully HTTPS while stopped: 502 Native project start: Successfully started HTTPS after recovery: 200

This test changed only the isolated sample project's process state and restored it in the same test. It did not require changing DNS, TLS, firewall rules or the working mapping.

7. Watch for a reboot startup delay
We previously saw a brief 502 while the VPS was coming back after reboot. The app then recovered automatically with Boot enabled. See Auto-start Node.js apps after reboot in aaPanel for the recovery test.

Allow a reasonable startup period and check the app log. If 502 persists, investigate it; do not assume that every 502 will resolve itself. If you manually start the app, record the intervention so you do not mistake it for successful automatic recovery.

8. Confirm the result
Check the expected response body as well as the status:

Code:Copy

curl -i http://127.0.0.1:3100/ curl -i https://node.adminslab.com/

Use normal TLS validation. Save the relevant error and the change that fixed it. If requesting support, include the aaPanel version, Node runtime, start command, listening port and redacted error excerpt. Keep credentials and private configuration values out of the post.

Related setup: Deploy a Node.js app in aaPanel with a domain and HTTPS.
Reference: aaPanel Node.js project documentation.]]> For a Node.js website behind aaPanel's Nginx mapping, a 502 Bad Gateway often means the web server could not get a usable response from the application. Start by testing the app locally, then compare its listening port with the mapping. Reinstalling Node.js or disabling the firewall is not a useful first diagnostic step.

Tested lab: aaPanel Free 8.0.7, Node.js 24.21.0, project afnodelab, app at 127.0.0.1:3100, domain node.adminslab.com. On 14 October 2026 we stopped only this sample app using aaPanel's native project controls, observed HTTPS 502, started it again and observed HTTPS 200. The app is restored and running.

1. Identify which layer fails
Run these checks over SSH on the VPS:

Code:Copy

curl -i http://127.0.0.1:3100/ curl -I https://node.adminslab.com/

Replace the sample port and domain with yours. The local request reaches the Node application directly. The domain request goes through DNS, TLS and the web server. Compare the results:

• Local connection refused + public 502: Check whether the app is running and whether the port is correct.
  
• Local 200 + public 502: Check the mapping's upstream address and port, then the website error log.
  
• Both return 200: The fault may have cleared. Check logs and monitoring before changing settings.
  
• TLS validation fails: Investigate the certificate separately; a certificate error is different from an HTTP 502 response.
  

2. Find the actual listening port
For our sample:

Code:Copy

ss -ltnp | grep ':3100'

The expected listener is 127.0.0.1:3100. We also tested 127.0.0.1:3101, where no app was listening, and curl returned connection refused. This demonstrates why guessing an upstream port is unreliable. We did not deliberately change the live mapping to that incorrect port.

If your app listens on another port, use that port in the local check and the aaPanel project settings. For an app behind a local reverse proxy, a localhost-only listener is appropriate. It does not need its application port opened publicly just to be reached by Nginx on the same machine.

3. Check project configuration
Open Website → Node.js Project, click the project name and inspect Project config. Compare the directory, start command, selected runtime, run user and port against the application's own configuration.


  node-app-config-20261014.jpg (Size: 191.89 KB / Downloads: 4)
Reference screenshot from the sample deployment: project port 3100, www user and Node.js runtime.

Changing the Project Port field does not rewrite a hard-coded port in server.js. The two must agree. Also check that the selected directory contains the expected package.json and startup file. Our sample uses start → node server.js and runs as www.

4. Read Project log before restarting
Open Project log. Look for the latest startup message and any error that precedes it.


  node-app-log-20261014.jpg (Size: 161.85 KB / Downloads: 3)
Reference startup log from the sample deployment shows the app listening on localhost:3100.

• Module not found: Check the application's dependency installation and selected runtime.
  
• Permission denied: Check the run user's access to the app directory and required resources.
  
• Address already in use: Identify the existing listener; do not start duplicate copies.
  
• App starts then exits: Read the exit error and check required environment variables or external services.
  

Do not switch the app to root or use permissions 777 to hide an access problem. Fix the specific missing permission instead.

5. Check the mapping
In Domain Manager, confirm the intended hostname is present. In Mapping, confirm mapping is enabled. Check the relevant web-server configuration read-only before making changes.

Our generated configuration contains:

Code:Copy

server_name node.adminslab.com; proxy_pass http://127.0.0.1:3100;

That upstream matches the app's listener. Configuration filenames differ between projects and versions; inspect the relevant site's configuration rather than editing an unrelated file. Prefer the panel's controls for changes, and validate the web-server configuration before reloading it.

6. Restore a stopped application
Use Service status → Start for a stopped project, or Restart when appropriate for the selected app. Confirm the action and wait for startup to finish. Repeat the local and domain checks; a Running label alone does not prove the application returns the expected page.

Our controlled test produced:

Code:Copy

Native project stop: Stopped successfully HTTPS while stopped: 502 Native project start: Successfully started HTTPS after recovery: 200

This test changed only the isolated sample project's process state and restored it in the same test. It did not require changing DNS, TLS, firewall rules or the working mapping.

7. Watch for a reboot startup delay
We previously saw a brief 502 while the VPS was coming back after reboot. The app then recovered automatically with Boot enabled. See Auto-start Node.js apps after reboot in aaPanel for the recovery test.

Allow a reasonable startup period and check the app log. If 502 persists, investigate it; do not assume that every 502 will resolve itself. If you manually start the app, record the intervention so you do not mistake it for successful automatic recovery.

8. Confirm the result
Check the expected response body as well as the status:

Code:Copy

curl -i http://127.0.0.1:3100/ curl -i https://node.adminslab.com/

Use normal TLS validation. Save the relevant error and the change that fixed it. If requesting support, include the aaPanel version, Node runtime, start command, listening port and redacted error excerpt. Keep credentials and private configuration values out of the post.

Related setup: Deploy a Node.js app in aaPanel with a domain and HTTPS.
Reference: aaPanel Node.js project documentation.]]>