Recommended Free Tools
The message is only a summary, not the diagnosis. Dokku rejected the Git push because a deployment hook failed somewhere in the process. Turn on Dokku trace mode, reproduce the push, and use the first specific error in the remote log to choose the fix. The failing phase is usually the app process, image build or download, host memory, SSH access, or the final nginx reload.
Antihost offers VPS plans with one-click Docker, NVMe storage and a 14-day free trial.
What “pre-receive hook declined” means in Dokku
A push such as git push dokku master is accepted by the SSH Git endpoint first. Dokku then runs its receive and deployment hooks: it detects the app, builds or retrieves an image, starts the declared processes, configures the proxy, and performs the checks required to finish the release. If any hook returns an error, Git reports a rejection similar to:
As an Amazon Associate I earn from qualifying purchases.
remote: -----> Deploying master (dokku)
remote: ...
remote: ! ERROR: ...
! [remote rejected] master -> master (pre-receive hook declined)
error: failed to push some refsThe final Git line does not say which operation failed. Dokku’s troubleshooting documentation describes it plainly: “The remote rejected error does not give enough information. Anything could have failed. Enable trace mode and begin debugging.” A rejected push can therefore be caused by a process that exits, a failed buildpack download, DNS or certificate problems, insufficient memory, an SSH identity problem, or a sudo failure while nginx is reloaded.
Do not change the Procfile, add swap, or edit sudoers based only on the last line. First capture the detailed remote output.
#1 Best Overall
First response: enable trace mode and save the complete log
- Enable Dokku trace mode using the trace controls documented for your installed Dokku release. If your release exposes trace as a CLI command, confirm the exact command with
dokku helpbefore running it. - Retry the same push that failed. Keep the terminal output from the first trace line through the final rejection; do not copy only the last ten lines.
- Save the output in a text file and redact private keys, tokens, passwords, and application secrets before sharing it.
- Find the first command that returns a non-zero status or the first explicit
ERROR. Later messages often describe the consequence, not the cause. - When the trace is still ambiguous, preserve the entire log for a Dokku issue or support request. A complete remote log gives maintainers the hook, plugin, and command context needed to reproduce the failure.
Trace output changes the problem from “Git rejected my branch” to a phase-specific question. Use the matching branch below rather than trying every fix at once.
Use the trace to identify the failing phase
| Evidence in the trace | Likely phase | Scope of the fix |
|---|---|---|
| A container or worker ends cleanly before deployment completes | Process startup | One application’s Procfile or process command |
| Build container, archive, curl, tar, dependency, or buildpack error | Build or download | Application build, network, DNS, certificate, or buildpack |
| Out-of-memory, killed process, or failure while installing dependencies | Host resources | Dokku host memory and swap |
Connection closed by <host> port 22, password prompt, or “not a repository” |
SSH authorization or identity | Client key, dokku account, or access policy |
sudo: a terminal is required to read the password during nginx reload |
Proxy finalization | Dokku user’s narrow sudo permission |
Fix an app or worker that exits immediately
A successful exit is not always a successful Dokku deployment. Dokku expects a web or worker process to remain attached to its container. If the command starts a daemon in the background and then exits, the container looks finished before Dokku can mark the deployment complete, so the push is rejected.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Recognize the pattern
The trace shows the process starting and then stopping without a crash, often with an exit status of zero. A common example is a Procfile worker entry such as:
worker: bin/delayed_job startbin/delayed_job start daemonizes: it launches work elsewhere and returns. Inside a container, that leaves no foreground process for Dokku to supervise.
Keep the process in the foreground
Change the worker command to its foreground form, for example:
worker: rake jobs:workUse the equivalent foreground command for your framework or queue system. The important property is that the command stays attached, continues emitting status, and exits only when the worker should actually stop. Commit the Procfile change, push again, and confirm that the worker remains running after deployment.
Do not “fix” this symptom by adding an arbitrary sleep. A sleep can hide the problem temporarily while the real worker is still detached.
Fix build and dependency-download failures
When trace output stops during image construction, identify the failed build container before retrying. On the Dokku host, list recently created build containers:
docker ps -a | grep buildChoose the image or container associated with the failed deployment and open it interactively:
docker run -ti IMAGE /bin/bashReplace IMAGE with the image identifier shown by Docker. From that shell, retry the failed download or build command. This separates a reproducible build error from a one-time network interruption and lets you inspect whether an archive is incomplete.
Check the failure in this order
- Read the actual curl or tar error. A truncated archive, checksum mismatch, timeout, and certificate error require different changes.
- Test outbound connectivity. Confirm that the host can reach the dependency or buildpack endpoint and that DNS resolves it consistently.
- Check for transient network conditions. Dokku identifies temporary network failures and buildpack bugs as common build-phase causes. Retry only after recording the original error so an intermittent success does not erase the evidence.
- Inspect resolver changes. If the host’s resolver configuration changed, Dokku documentation shows
resolvconf -uas a possible corrective step. Verify the resolver setup used by the host and Docker before repeating the build. - Check certificate configuration. An application variable named
SSL_CERT_FILEcan interfere with dependency downloads when it is being used for an unrelated purpose. Rename that application variable, or set it to the correct certificate file only when the application genuinely needs it.
Allow more time for slow links
For a consistently slow but reachable connection, increase Dokku’s global CURL_TIMEOUT and CURL_CONNECT_TIMEOUT settings through the configuration method supported by your Dokku version. These are host-wide settings, so document the new values and consider the effect on every application. A longer timeout cannot repair a broken DNS route, an incomplete archive, or a bad certificate.
Fix memory pressure and missing swap
Dependency installation can exceed the memory available on a small Dokku host. Dokku’s advanced-installation documentation warns that hosts with less than 1 GB of memory can show a pre-receive rejection while installing NPM dependencies. The process may be killed by the kernel, leaving the Git client with only the generic rejection.
Confirm an out-of-memory failure
Before changing the host, inspect current memory and swap:
free -h
swapon --showLook for an out-of-memory kill or a process terminated under memory pressure in the host’s kernel and service logs. An OOM message, rather than the mere fact that the server is small, is the evidence for choosing a resource fix.
Do these 3 things before closing this tab:
1Repair Windows errors before they cause bigger problems2Fix the driver behind crashes, sound loss and screen glitches3Clear out junk files and repair common Windows errorsAdd swap using Dokku’s documented procedure
Dokku documents adding swap as the workaround. Its example turns a 512 MB host into a system with 1 GB of swap-backed capacity and notes that swap may be increased to a maximum of twice the physical memory. Follow the swap procedure for your operating system and verify the result with swapon --show. Treat swap as protection against short memory spikes, not as a substitute for adequate RAM: builds can become extremely slow when they page heavily.
After the change, rerun the same build. If the trace still shows an OOM kill, reduce build concurrency or move the application to a host with more physical memory rather than repeatedly pushing the unchanged workload.
Fix SSH access, account, and identity errors
Some apparent deployment failures occur before Dokku can build anything. The trace may show an SSH connection closing, a password request, or a message that the target app is not a repository.
Connection closes on port 22
For an error such as Connection closed by <host> port 22, check whether the dokku account is permitted by /etc/security/access.conf. A restrictive access rule can terminate an otherwise valid SSH session before Git reaches Dokku’s command handler. Correct only the rule needed for the intended source and then test SSH again.
Git asks for a password or cannot find the app repository
Dokku uses SSH keys rather than an interactive Git password. Verify that the private key on the client matches the public key added to Dokku with sshcommand acl-add. Check that the key is readable by the user running Git and that the remote URL names the correct Dokku host and application.
A per-host SSH configuration can make the identity explicit:
Host dokku.example.com
User dokku
IdentityFile ~/.ssh/id_ed25519
IdentitiesOnly yesReplace the hostname and key path with your values. Test the same host and user that the Git remote uses; testing a different alias can validate the wrong key. Once SSH authentication succeeds, repeat the push and return to the deployment phase shown by trace output.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Fix a late nginx reload or sudo failure
Dokku can build the image and start the app successfully, then reject the push while reloading nginx. One documented failure ends with:
Free tools Windows power users keep installed
One-click scans. No signup required.
sudo: a terminal is required to read the passwordThis means the non-interactive Dokku user attempted a sudo command that requires a password or is not covered by the intended sudo policy. The deployment is therefore rejected even though the application process may already exist.
Correct the permission narrowly
Inspect the sudoers configuration for the dokku user and the exact nginx commands used by your installation. Grant non-interactive permission only for those required commands, using the syntax and file locations appropriate to your operating system. Do not copy an unrestricted ALL=(ALL) NOPASSWD:ALL rule as a shortcut.
Best Value
Validate the rule with a non-interactive test, reload nginx through Dokku, and then push again. If the app is already running but the proxy is stale, check the generated proxy configuration and nginx service logs before changing application code.
Verify the deployment after the push succeeds
- Repeat the original push with trace still enabled so you can confirm that the previously failing phase completes.
- Check that the expected web and worker processes remain running rather than exiting immediately.
- Check Dokku’s process and proxy reports for the application; releases that provide these commands commonly use forms such as
dokku ps:report APPanddokku proxy:report APP. - Request the application through its configured hostname and inspect the app and nginx logs for startup or upstream errors.
- Disable trace mode after troubleshooting if your Dokku version provides a trace-off control. Leaving verbose command output enabled can expose operational details in later sessions.
A successful Git response alone is not enough: the process must stay up and the proxy must route to it. Conversely, if the app is healthy but the push still fails, return to the trace and locate the first non-zero hook command; a later cosmetic message is unlikely to be the root cause.
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 →Choose the smallest change that matches the evidence
| Fix | When it is justified | Persistence and scope |
|---|---|---|
| Foreground Procfile command | Worker or web process exits before deployment completes | Persistent change to one application |
| Interactive build-container investigation | Build, archive, curl, or dependency command fails | Diagnostic; application build or network dependent |
| Resolver or timeout adjustment | Trace shows DNS, slow transfer, or connection timeout | Resolver may affect the host; curl timeout is global in Dokku |
| Swap or more RAM | Kernel/OOM evidence during dependency installation | Host-wide resource change |
| SSH access or key correction | Port 22 closure, password prompt, or repository identity error | Account, client, or host access policy |
| Narrow nginx sudo rule | Deployment reaches proxy reload and sudo requests a terminal/password | Host-wide permission, limited to required commands |
Make one relevant change at a time and retain the trace from each attempt. That preserves causality and prevents a broad permission or resource change from masking the original failure.
When to stop retrying and ask for help
Open a Dokku issue or contact the person who maintains the host when the trace does not identify a failing command, when the same hook fails after its documented prerequisite is present, or when changing a host-wide permission or resource setting could affect other applications. Include the Dokku version, operating-system version, deployment method, app name without secrets, and the complete redacted remote log. The full sequence is more valuable than a screenshot of “pre-receive hook declined.”
The reliable workflow is therefore simple: expose the hook with trace mode, classify the first concrete error, apply the narrow fix for that phase, and verify both the process and proxy after pushing again.
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.
