A Dokku 502 is usually a symptom, not an nginx problem to solve by blindly restarting services. Dokku deliberately returns 502 Bad Gateway when an app has not been deployed, has no web process type, or has no running web processes. Start by checking process health and the per-app nginx error log, then verify the host-to-container port mapping, listener binding, generated configuration, and Ubuntu firewall path in that order.
Antihost offers VPS plans with one-click Docker, NVMe storage and a 14-day free trial.
The commands below use APP as a placeholder for your Dokku application name. Replace it with the exact name shown by Dokku.
As an Amazon Associate I earn from qualifying purchases.
Recommended Free Tools
What a 502 means in Dokku
In a Dokku deployment, nginx is the public-facing proxy. It must be able to forward a request to a running web process inside the app container. If that upstream does not exist or cannot be reached, nginx returns 502.
“when an app is created but not yet deployed, has no
webprocess type, or has no running web processes, Dokku generates a minimal nginx configuration that returns502 Bad Gatewayresponses.”#1 Best Overall
Sale
Gaoye Blue Light Blocking Glasses
- BLUE LIGHT BLOCKING GLASSES: Our blue light glasses for women boast UV400 protection, blocking harmful blue rays from computer screens. With these bluelight glasses women, you can enjoy gaming, reading, or watching TV with no worries of eye strain.
- EYE RELIEF: Our blue light glasses are engineered to reduce blurry vision or strain caused by prolonged screen time. These womens blue light glasses aid in better sleep by preventing blue light from disrupting your natural sleep cycle, helping you fall asleep faster and enjoy a more restful night's sleep, making them the perfect christmas present.
- COMFORTABLE: Crafted from durable material, our trendy blue light glasses for woman or blue light glasses men ensure long-lasting comfort. The high-transmittance lenses accessories, gamer gifts for men, help keep your eyes relaxed. Perfect stocking stuffers, gifts for gamers men, christmas gifts for men, halloween costumes.
- LIGHTWEIGHT: These clear blue light glasses feature a lightweight frame, meaning they’ll stay comfy for long-term wear. Perfect as blue blockers glasses for women or mens blue light glasses, these non-prescription fake glasses for men can be worn throughout the day. The blue light blocking glasses women feature polycarbonate HD lenses, which are anti-reflective and restore true color.
- WORRY-FREE PURCHASE: If you experience any issues, our support team is ready to assist you quickly. These are the perfect costume glasses for cosplay dressing up.
Dokku documentation, Nginx Proxy page
That behavior creates five useful troubleshooting layers:
- Process health: the app has no running
webprocess, or the process starts and exits. - Port routing: Dokku’s proxy map points to an internal port different from the one your server uses.
- Listener binding: the process is running but listens only on an unreachable address, rather than the container’s network interface.
- nginx configuration: the generated app configuration is invalid or stale.
- Firewall path: Ubuntu firewall rules interfere with the request path even after deployment succeeds.
Use evidence from the failing layer before changing another layer. A restart cannot create a missing process type, repair a wrong port map, or fix an application that immediately crashes.
Quick triage: match the symptom to the layer
| Evidence | Likely layer | First corrective action |
|---|---|---|
ps:report shows no running web process |
Process formation or application health | Repair the Procfile or process definition, fix the start command and required environment, then redeploy. |
| Error log says the upstream connection was refused | No listener, crashed process, wrong bind address, or wrong port | Check the container’s process and listening port, then compare it with ports:report. |
| Error log shows an upstream timeout | Slow or wedged application process | Inspect application logs and determine why the web process is not responding. |
| Error log indicates an upstream address or port mismatch | Dokku port mapping | Set the external-to-internal mapping to the port the web server actually uses. |
nginx -t or Dokku validation fails |
Generated nginx configuration | Inspect the app configuration, correct the source setting, rebuild it using the command for your Dokku release, and validate again. |
| Deployment succeeds but requests fail from outside the host | Firewall or host networking | Review UFW and other host firewall rules while reproducing the request and watching the nginx error log. |
Step 1: Confirm that Dokku has a healthy web process
Begin with Dokku’s process report and recent application output:
dokku ps:report APP
dokku logs APP --tailA web-facing deployment needs a running process named web. If the report has no web process, nginx has nothing to proxy and a 502 is expected.
If no web process exists
Check how the application forms processes. A Procfile or equivalent process definition must create a web entry, and that entry must launch the server rather than a one-time task. Correct the process definition and redeploy. Do not try to solve this state with an nginx reload: nginx cannot proxy a process Dokku never started.
If the web process repeatedly exits
Read the tail of the app log for the actual startup failure. Common evidence includes a bad start command, a missing environment variable, a migration or initialization failure, or a binding error. Fix the reported application problem, deploy again, and run dokku ps:report APP until the web process remains running.
Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchPC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11A deployment message can report success even when the resulting web process is unhealthy. Treat the process report and runtime log as the authority for availability, not the fact that an image was built.
Step 2: Read nginx’s per-app evidence while reproducing the 502
With the failing request ready to reproduce, inspect the app-specific nginx data:
dokku nginx:error-logs APP -t
dokku nginx:access-logs APP
dokku nginx:show-config APPDokku’s default per-app files are /var/log/nginx/APP-error.log and /var/log/nginx/APP-access.log. The error log identifies what nginx could not do; the access log confirms the request and status code; the generated configuration shows which upstream and directives Dokku currently installed.
Rank #2
- WINDEX GAMING WIPES: effortlessly clean all your gaming gear and gaming electronics in one easy step with our new Windex Gaming Wipes
- AMMONIA FREE: our ammonia-free formula is safe to use on all of your favorite gaming equipment like consoles, headsets, controllers, screens, keyboards, and more
- PRE-MOISTENED WIPES: each wipe instantly removes dust, dirt, and stubborn smudges and fingerprints leaving a streak-free shine
- ANTI-STATIC: great for cleaning and wiping down your gaming gear and electronics leaving behind no visible residue
- COMPACT RESEALABLE PACKAGE: store your pack of Windex Gaming Wipes anywhere in your home for whenever a quick and easy wipedown is needed
Interpret the error text
- Connection refused generally means that nothing is accepting connections at the configured upstream address and port. Check whether the web process is alive, whether it is listening on the expected port, and whether it bound to a reachable address.
- Upstream timeout indicates that nginx connected or attempted to connect but did not receive a response in time. Follow the application log for a blocked request, startup stall, or wedged process rather than changing ports at random.
- Upstream address or port mismatch points to a proxy map that does not match the port used by the application. Verify the map before touching nginx templates.
Run the log command with the -t option while generating a request so the newest failure is easy to separate from older incidents.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Step 3: Verify Dokku’s port map and the container listener
Ask Dokku which internal port it is proxying:
dokku ports:report APPCompare the reported internal port with the port on which the application’s web server actually listens. The external side is normally HTTP port 80 in a mapping such as http:80:5000; the internal value must be the application’s real listening port.
Correct an incorrect mapping
Set the mapping with the actual internal port:
dokku ports:set APP http:80:INTERNAL_PORTFor an application that genuinely listens on port 5000, the concrete example is:
dokku ports:set APP http:80:5000Do not copy 5000 merely because it appears in the example. Substitute the port used by your image and framework. After changing the map, inspect it again with dokku ports:report APP and reproduce the request.
Check the bind address inside the container
The server must bind to 0.0.0.0:<port> so it is reachable through Docker networking. A process that listens only on its loopback interface can appear healthy inside the container while remaining unreachable to Dokku’s nginx proxy.
Also inspect the image’s Dockerfile. An EXPOSE value and Dokku port settings influence proxy configuration, but an EXPOSE declaration does not make a server listen by itself. The application command and its bind address still determine whether a listener exists.
Step 4: Validate and reload nginx safely
Once process health and port routing are correct, validate the configuration before reloading it:
sudo nginx -t
dokku nginx:validate-config APP
dokku nginx:reloadValidation and reload are separate operations. If validation reports an error, do not reload. Use:
dokku nginx:show-config APPto inspect the generated app configuration and identify the incorrect directive, upstream, or included file. Correct the setting that produced the bad configuration, then rebuild the generated app configuration using the command provided by your installed Dokku release. Dokku releases can differ in how that rebuild is invoked, so use the command documented for the version on your server rather than guessing a subcommand. Run both validation checks again; reload only after they succeed.
Do these 3 things before closing this tab:
1Clear out junk files and repair common Windows errors2Fix the driver behind crashes, sound loss and screen glitches3Repair Windows errors before they cause bigger problemsRank #3
- Ergonomic & Adjustable Design: Fight "text neck" and improve your posture. Designed for comfort, it offers an adjustable height (7.1in-8.5in) (1.4in adjustable range) and angle (5°-85°) Please note: cell phone stand is only 9 inches tall—the length of a standard pencil
- Without blocking subtitles Perfect for office desk Tiktok Face Time Zoom video—this is the ultimate kitchen desk essential for phones! Perfect viewing experience while reducing neck back strain, A must-have for gamers streamers desk, and anyone who values both style and support!
- Sleek & Stable Design fits Otterbox Case: Say goodbye to bent cables, tangles, and tip-overs! LISEN’s stylish adjustable desk phone holder features a built-in charging hole and smart cable management, keeping your phone secure and your workspace clutter-free cool gadgets for men
- ANTI-SLIP DESIGN free hands: The under 10.00 items easy gadgets back and the bottom of this kitchen essentials for women are fully covered by anti-skid silicone, which LISEN stand up desk decor can provide maximum protection device from any scratches and slides
- Your Perfect Viewing Companion:If your product arrives damaged or breaks within 365 days, reach out to LISEN for a quick and hassle-free solution. Struggling with assembly, like tightening the screw? We’ve got your back! Your experience matters to us. (Product including: phone Holder stand*1, screw*1, hexagon screwdriver*1, specification*1)
When a stale generated configuration is suspected
A changed port map or application setting should be reflected in the generated configuration. If ports:report shows the right value but nginx:show-config still contains the old upstream, treat the generated file as stale: inspect it, rebuild it with your release’s supported command, validate, and reload. This keeps the correction tied to the source setting instead of editing a generated file that Dokku may overwrite.
Step 5: Check Ubuntu’s firewall path
Dokku’s troubleshooting guidance identifies a firewall such as UFW as a possible cause of Bad Gateway on Ubuntu. This matters when the image builds and the process report looks healthy, yet requests still fail.
Review UFW and any other host firewall policy. Confirm that public HTTP and HTTPS traffic can reach nginx and that host rules do not block the Docker/Dokku path between nginx and the app. Reproduce the request while following dokku nginx:error-logs APP -t; a new log entry helps distinguish a firewall symptom from an application refusal or timeout.
Do not weaken firewall rules indiscriminately. Change only the rule that blocks the required HTTP/HTTPS or Docker/Dokku path, then retest from the same client that reported the 502.
Free tools Windows power users keep installed
One-click scans. No signup required.
Step 6: Retest and isolate the failing layer
Use a direct header request after each corrective change:
curl -I http://APP.example.comInterpret the result together with the change that preceded it:
- If the response changes after the web process is started and remains healthy, process availability was the fault.
- If it changes after
dokku ports:set, the proxy was targeting the wrong internal port. - If nginx validation fails, repair the generated configuration or its source setting before attempting another reload.
- If the map is correct but the error log still reports refusal, return to the container’s bind address, listener state, crash output, and process health.
- If local checks are correct but outside requests still fail, continue with the firewall and host-network path.
Keep the error log open during the test. A successful status from one layer does not prove that the next layer is reachable; the sequence of process, listener, proxy, and firewall checks narrows the fault without mixing unrelated changes.
Common 502 scenarios and the appropriate fix
The app was just created
A newly created app that has not yet been deployed can receive a deliberate 502 from Dokku’s minimal nginx configuration. Deploy an application that defines a web process; there is no upstream to repair until a deployment creates one.
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEFix the driver behind crashes, sound loss and screen glitchesFind Drivers →The deploy completed but no web process is running
Use dokku ps:report APP and dokku logs APP --tail. Correct the process definition, startup command, environment, migration step, or bind failure shown in the logs. Restarting before fixing that cause only repeats the crash.
Rank #4
- Easy Installation: Our gaming lights have been designed to enhance your entertainment experience. Simply position the led light bar next to your TV or game console to create a game room environment with ease. They come with USB power and a 60 inch cord for direct mounting and mobility
- Audio Syncing & Extensive Mode: The built-in high-sensitivity music sensor allows you to sync the TV led lights to your favorite music. Lights react and move to the beat of music, film and game audio, creating an incredible immersive sound and light experience – and all without the need for an additional hub. You can choose from 64+ patterns, including strobe, illusion, jump, energy, gradient, running, chasing, fluttering mode etc. Each mode can be applied to different scenes
- 64+ Chasing IC+RGB & W Effect: The independent control design of IC+RGB and white all-in-one multifunctional rgbw led bar lights monitor backlight allows you to easily switch the led lights for desk between IC+RGB and white to enjoy a variety of lighting effects, you can choose white lighting mode with high brightness for better illumination when working, etc. Choose IC+RGB lighting mode when you need to create an entertaining atmosphere for the light show, 16 million colours of Color changing rgb light bar let you dance to the beat and create a dynamic party atmosphere
- Dynamic and Dimmable Lights: 1%-full brightness free brightness adjustment gives you the flexibility to adjust dimmable led light bar for room decorations or a variety of occasions
- USB Powered: USB light bars for room can be powered by powernank, usb charger, TV, Monitor, laptop PC mainframe, making behind TV led lighting bar easy to install in any location.TV led lights are powered by the TV usb interface / PC mainframe, can be turned on/off synchronously with TV / PC
The app listens on a different port than Dokku expects
Use dokku ports:report APP, identify the application’s real listening port, and set http:80:INTERNAL_PORT accordingly. Verify the process binds to 0.0.0.0 and that the Dockerfile’s EXPOSE value is consistent with the intended web port.
The nginx configuration is stale or invalid
Inspect dokku nginx:show-config APP, rebuild the generated configuration with the command supported by your Dokku release, run sudo nginx -t and dokku nginx:validate-config APP, then reload.
Only external requests fail
Review UFW and host firewall policy while reproducing the request. Ensure public HTTP/HTTPS reaches nginx and that the Docker/Dokku route is not blocked. Use the per-app nginx logs to verify whether the request arrives and where it stops.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Choose the remedy by evidence
Several fixes can appear plausible, but they do not have the same scope or persistence. A process-definition change and redeploy is the durable remedy when no web process exists. A port change with dokku ports:set is durable in Dokku’s settings and should be repeated only if a later deployment or configuration change replaces it. Rebuilding generated nginx configuration repairs drift without changing the application itself. Reloading nginx is an activation step, not a diagnosis. A restart is useful only after the process, port, and bind settings are correct; it cannot create a missing process or make a server listen on another port. Firewall changes affect the host path and should be limited to the blocked HTTP/HTTPS or Docker/Dokku traffic.
Prefer the smallest change supported by the evidence. If the error log says “connection refused,” changing timeout values is not a substitute for starting the listener. If the generated configuration is invalid, repeatedly redeploying the application can leave the same proxy error in place. If only outside clients fail, changing the app’s start command may hide the real UFW or host-networking issue.
Operational pitfalls to avoid
- Confusing image success with service success: a successful build or deploy message does not prove that a stable
webprocess exists. - Using the sample port blindly: 5000 is an illustration, not a universal Dokku port. Match the map to the listener reported by the application.
- Binding to loopback: listening on
127.0.0.1inside the container can pass an in-container check while blocking nginx. - Editing generated files directly: Dokku can overwrite generated configuration. Correct the source setting and rebuild with the supported release-specific command.
- Reloading unvalidated nginx: always run
sudo nginx -tand Dokku validation beforedokku nginx:reload. - Changing multiple layers at once: make one evidence-based change, then run
curl -Iand correlate it with the newest log line. - Disabling the firewall broadly: adjust only the rule that blocks the required path, and verify the result from the same client.
Preflight details to record
Before making a change, record the exact app name, Dokku version, deployment method, framework or Dockerfile, internal listen port, and the newest nginx error text. These details determine whether the process comes from a Procfile or image entrypoint, whether EXPOSE influences the proxy settings, and which configuration-rebuild command is available. Keeping the original ps:report, ports:report, and nginx:show-config output makes it easier to verify that a fix changed the intended layer and to restore a previous setting if necessary.
A repeatable recovery order
- Set the exact app name in place of
APP. - Run
dokku ps:report APPanddokku logs APP --tail; establish that a stablewebprocess exists. - Follow
dokku nginx:error-logs APP -twhile reproducing the 502. - Run
dokku ports:report APPand compare the map with the server’s actual internal port. - Confirm the server binds to
0.0.0.0:<port>and that the Dockerfile’sEXPOSEdeclaration, when present, names the intended port. - Inspect
dokku nginx:show-config APP; rebuild generated configuration if it does not reflect current settings. - Run
sudo nginx -tanddokku nginx:validate-config APP. - Reload with
dokku nginx:reloadonly after validation succeeds. - Check UFW and other host firewall rules if the request still fails after the application and proxy checks pass.
- Run
curl -I http://APP.example.comand correlate the result with the newest nginx log entry.
What depends on your Dokku and application versions
The final command or setting can vary with the Dokku release, application framework, Dockerfile or buildpack, internal listen port, and exact nginx error text. The diagnostic sequence remains the same, but the process command, environment variables, and configuration-rebuild command must match your application and installed Dokku version. Use the observed process report, logs, port report, and generated configuration to choose the branch instead of applying an app-specific value that has not been verified.
Frequently Asked Questions
Why does Dokku show 502 immediately after I create an app?
Dokku intentionally returns 502 for an app that has not been deployed, has no web process type, or has no running web processes. Deploy a release that defines a stable web process before troubleshooting nginx.
What is the fastest command to see why my Dokku app is returning 502?
Run dokku nginx:error-logs APP -t while reproducing the request. Pair it with dokku ps:report APP and dokku logs APP --tail so you can distinguish a refused connection, timeout, crashed process, or bad port.
Best Value
- Compatible with Wide Screens - To ensure compatibility with the dual monitor mount, your each monitor must meet three conditions at the same time: First, computer screens size range: 13 to 32 inches. Second, screen weight range: 4.4 to 19.8 lbs. Third, the back of the monitor screen must have VESA mounting holes with a pitch of 75x75mm or 100x100mm.
- Regarding the compatibility with desks - Your desk must meet three conditions at the same time: First, desk material: Only wooden desks are recommended, plastic or glass desks cannot be used. Second, desk thickness range: 0.59" - 3.54". Third, the bottom of the desk should not have any cross beams or panels, as this will interfere with installation. We recommend carefully checking that your desk and monitors meets all above conditions before purchasing.
- Dual C-Clamp Hold - Worried your dual monitors might wobble or slip? Our upgraded base uses a larger platform plus a dual C-clamp structure to lock the dual monitor arm firmly to your desk. Each arm safely keeps your screens steady while you type, click and game—no shaking, no sliding, just a clean and secure setup you can trust every day. It also provides Grommet Mounting installation choice, both options ensure stable and secure fixation for your 0.59" - 3.54" desk.
- Full-Motion Adjustment For Comfortable View - Pull the screen closer when you’re deep in a spreadsheet, push it back to watch videos, or rotate to portrait for coding — moving everything smoothly with just one hand. The monitor stand offers +85°/-50° tilt, ±90° swivel and 360° rotation. Raise your monitor up to 15.75″ to support a healthy sitting posture. Whether you’re working from home, gaming through the night, or switching between video calls and documents, getting the screens to your natural line of sight helps relieve neck, shoulder and back strain so you can stay focused longer with less fatigue.
- Keep Your Desk Organized: By lifting both screens off the desktop, this dual monitor stand opens up valuable space for your keyboard, notebook, docking station or a simple, clutter-free work area. Built-in cable management guides wires along the arms, keeping cords out of sight and out of the way. Enjoy a tidy, modern workstation that looks as good as it feels to use.
How do I know which port Dokku is proxying?
Run dokku ports:report APP. Compare the internal port in the report with the port your web server actually listens on, then correct it with dokku ports:set APP http:80:INTERNAL_PORT if necessary.
Is port 5000 required for Dokku apps?
No. Port 5000 is only an example. Replace it with the real internal listen port used by your image or framework. The process must also bind to 0.0.0.0, not only to loopback.
Can restarting Dokku or nginx fix a 502 by itself?
Only when the underlying process and configuration are already correct and a transient restart is appropriate. A restart cannot create a missing web process, repair an incorrect port map, or fix an application that exits during startup.
What should I do when nginx validation fails?
Do not reload. Inspect dokku nginx:show-config APP, correct the source setting or template, rebuild the generated app configuration with the command supported by your Dokku release, and run sudo nginx -t and dokku nginx:validate-config APP again.
Why does the app work inside the container but still return 502?
The server may be bound only to 127.0.0.1 or another unreachable address. Bind it to 0.0.0.0:<port>, ensure Dokku maps to that same port, and verify the generated nginx upstream.
Can UFW cause a Dokku 502 after a successful deploy?
Yes. Dokku identifies UFW or another host firewall as a possible cause. Confirm that HTTP/HTTPS reaches nginx and that host rules do not block the Docker/Dokku path, then reproduce the request while following the per-app nginx error log.
Recommended Free Tools
Where are Dokku’s default nginx logs?
The default per-app files are /var/log/nginx/APP-error.log and /var/log/nginx/APP-access.log. The Dokku log commands are preferable because they select the app and can follow new entries during a test.
What information should I collect before asking for help?
Record the app name, Dokku release, deployment method, framework or Dockerfile, internal listen port, dokku ps:report APP, dokku ports:report APP, recent application logs, the newest nginx error line, and dokku nginx:show-config APP. These outputs identify which layer is failing without guessing.
The Bottom Line
Fix a Dokku 502 from the inside out: establish a stable web process, read the per-app nginx error, make Dokku’s port map match a listener bound to 0.0.0.0, validate and reload generated nginx configuration, then check UFW when only external traffic fails. Re-test with curl -I after each evidence-based change.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →
