The message is only a summary, not the cause. Dokku rejected the Git push because a deployment hook failed somewhere in the process. Turn on Dokku trace mode, repeat the push, and use the first concrete error in the expanded output to choose the fix—whether the app process exited, a build download failed, the host ran out of memory, SSH rejected the connection, or nginx could not reload.
Antihost offers VPS plans with one-click Docker, NVMe storage and a 14-day free trial.
What “pre-receive hook declined” actually means
A failed Dokku push often ends with a line similar to:
As an Amazon Associate I earn from qualifying purchases.
Free tools Windows power users keep installed
One-click scans. No signup required.
! [remote rejected] master -> master (pre-receive hook declined)
error: failed to push some refsGit is reporting the result of a server-side hook. Dokku received the objects, started its deployment workflow, and then rejected the push because one of the workflow stages failed. The final Git line does not tell you which stage failed. A process can exit, a build can fail to download a dependency, an SSH policy can close the connection, or a completed deployment can fail during the nginx reload. Treating the last line as the diagnosis leads to random changes and repeated failed pushes.
Dokku’s troubleshooting guidance describes the message as insufficient on its own: anything in the deployment could have failed, so tracing must come first. The useful evidence is the expanded remote output immediately before the rejection.
#1 Best Overall
First response: enable trace mode and capture one complete push
Do this on the Dokku host before retrying. Trace output can include paths, commands, and environment details, so store it securely and remove secrets before sharing it.
- Enable tracing. On current Dokku installations, run
dokku trace:onas an administrator on the server. - Push once and save all output. From the application repository, repeat the same push that failed, for example
git push dokku master 2>&1 | tee dokku-push.log. If your deployment branch is different, use that branch instead ofmaster. - Find the first concrete error. Read upward from the final rejection until you reach the first failed command, failed download, permission error, out-of-memory message, or process-exit notice. Later lines are often consequences.
- Turn tracing off after collection. Run
dokku trace:offwhen you have finished troubleshooting so normal pushes do not expose unnecessary command detail.
If the trace still ends without a specific cause, preserve the entire remote log—not just the last Git line—when asking for help in a Dokku issue or support channel. The sequence of hook commands is what lets someone identify the failing phase.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Use the trace to select the right branch
| Failing phase | Typical evidence in the trace | Scope of the fix | First action |
|---|---|---|---|
| App or worker process | Container or worker ends cleanly before deployment completion | Usually one application | Keep the declared process attached in the foreground |
| Build or dependency download | Build command, curl, archive, DNS, or buildpack error |
Application build; sometimes host networking | Inspect the failed build container and repeat the exact command |
| Memory and swap | Out-of-memory messages or failure while installing NPM dependencies | Whole host | Check memory pressure and add appropriately sized swap |
| SSH identity or access | Connection closed by <host> port 22, password prompt, or “not a repository” |
Client, account, or host access policy | Verify the dokku account, access rules, and private key |
| nginx reload and sudo | Deployment appears complete, then sudo reports that a terminal is required | Host permission and proxy reload | Correct the narrow sudo permission for the command that failed |
When the app or worker exits immediately
Dokku expects the process declared for each process type to remain attached while it runs. A command that daemonizes—starts a background service and then exits—can return success inside the container while leaving Dokku with no running process to complete the deployment. Dokku then rejects the push even though the command itself did not print an obvious failure.
Check the Procfile command
Open the deployed application’s Procfile and compare each process command with the trace. Look for commands containing a daemonizing or background mode. The documented example is a worker declared as:
worker: bin/delayed_job startThat command starts the worker as a daemon and exits. A foreground variant keeps the worker attached:
worker: rake jobs:workUse the equivalent foreground command for your framework and worker implementation. The important property is not the specific Ruby command; it is that the process remains attached to the container instead of forking into the background.
Retry only after the process definition is changed
Commit the corrected Procfile, push again with tracing enabled, and confirm that the worker remains running through the end of the deployment. If the trace shows a different process type exiting, apply the same foreground rule to that process rather than changing unrelated build or SSH settings.
When the build phase fails
A build failure occurs before the new application image is ready. Common evidence includes a failed buildpack step, an incomplete archive, a curl or tar error, DNS lookup failures, or a dependency download that times out. Dokku identifies transient network problems and buildpack bugs as recurring causes, so retrying blindly can produce a different result without fixing the underlying condition.
Open the failed build container
First list recently stopped build containers:
docker ps -a | grep buildIdentify the image associated with the failed build and open it interactively:
docker run -ti IMAGE /bin/bashReplace IMAGE with the image name shown by Docker. Inside the container, repeat the exact download or build command that failed. This separates an application dependency problem from a transient failure in the original hook and lets you inspect whether the archive is complete.
Check connectivity, DNS, and archive integrity
- Read the actual
curlor archive error; “download failed” is not specific enough. - Verify that the host can resolve the dependency’s hostname and establish an outbound connection.
- Check whether a partial archive was cached or downloaded before the failure.
- If the host resolver changed after a network update, the Dokku documentation identifies
resolvconf -uas a possible corrective step.
After correcting the network or dependency issue, leave the interactive container and repeat the normal Git push. Do not treat a successful manual download as proof that every build will succeed; the important test is a complete Dokku deployment.
Adjust slow-download settings carefully
For a slow but functioning link, Dokku supports increasing the global CURL_TIMEOUT and CURL_CONNECT_TIMEOUT configuration values. Increase them only after the trace shows a timeout; a larger timeout does not repair DNS, TLS, or a broken remote archive.
Also inspect application configuration for SSL_CERT_FILE. Dokku documents cases where this key interferes with dependency downloads. If your application uses that variable for another purpose, rename the application variable and retry so the build tooling can use its expected certificate behavior.
When memory or swap is inadequate
Dependency installation can exceed the available memory even when the application itself is small. Dokku’s advanced-installation guidance specifically notes rejection on hosts with less than 1 GB of memory while installing NPM dependencies.
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 matchWindows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallConfirm memory pressure before changing the host
Check current memory and swap, for example:
free -h
swapon --showThen inspect the trace and host logs for an out-of-memory kill. If there is no memory evidence, do not add swap as a speculative fix; continue with the phase identified by tracing.
Add swap within the documented limit
The documented example turns a 512 MB host into a system with 1 GB of swap-backed capacity. Dokku states that swap may be increased up to a maximum of twice the host’s physical memory. Use your operating system’s supported swap procedure, verify the new swap with swapon --show, and account for the fact that this is a host-wide, persistent resource change. Swap can prevent an installer from being killed, but it does not substitute for adequate RAM during sustained workload.
After the change, rerun the same build. If the build now completes but another phase fails, follow the new trace evidence rather than continuing to tune memory.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.When SSH access or the identity is wrong
Not every apparent pre-receive rejection is a build problem. If the trace or Git output contains Connection closed by <host> port 22, investigate the SSH account and access policy first.
Quick wins for a faster PC:
Repair Windows errors before they cause bigger problemsFix Now →Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Clear out junk files and repair common Windows errorsFree Scan →Check the Dokku account policy
Verify that the dokku account is permitted by /etc/security/access.conf. A restrictive rule can close the session before Dokku receives the repository, leaving Git with an unhelpful remote error.
Check the key used for the push
If Git asks for a password or reports that the application is not a repository, make sure the client is offering the private key corresponding to the public key added with Dokku’s sshcommand acl-add. Confirm the key file exists locally and that your SSH agent or configuration selects it for the Dokku host.
Best Value
A minimal client configuration can make the identity explicit:
Host dokku.example.com
User dokku
IdentityFile ~/.ssh/id_ed25519Replace the hostname and key path with your actual values. Do not copy a key from another user or disable host-key checking to work around an identity error. Once SSH authentication succeeds, repeat the push with tracing to see whether a separate deployment phase is still failing.
When nginx reload or sudo fails at the end
A deployment may build the image, start the application, and still be rejected during the final proxy update. One documented failure ends with:
sudo: a terminal is required to read the passwordIn that situation, the application can be healthy while Dokku cannot reload nginx through the dokku user’s sudo policy.
Fix only the permission that failed
Review the sudo configuration for the dokku account and grant the narrowly scoped permission required by the nginx reload command used by your installation. Avoid copying an unrestricted rule such as allowing every command as root. The correct rule depends on how Dokku and nginx were installed; match the exact executable and arguments shown in the trace, validate the syntax, and then retry the push.
If the reload succeeds on the next attempt, verify both sides of the deployment: the application process is running and the proxy serves the expected response. A successful image build alone does not prove that traffic is reaching the new release.
Compare fixes by evidence and blast radius
| Fix | Evidence that justifies it | Temporary or persistent | Applications affected |
|---|---|---|---|
| Change a daemonizing Procfile command to a foreground command | Worker or container exits before completion | Persistent in the application repository | That process in one application |
| Retry a download or correct resolver settings | DNS, connection, incomplete archive, or transient build error | Retry may be temporary; resolver change persists on the host | One build, or all builds using the host resolver |
| Increase curl timeout values | Trace shows connection or transfer timeout on a slow link | Persistent Dokku configuration | Builds using the global settings |
| Add swap | Out-of-memory evidence, especially during NPM installation on a small host | Persistent host resource change | All workloads on that host |
| Correct SSH access or identity | Port 22 closure, password prompt, or repository/authentication error | Persistent account or client configuration | Users or repositories using that access path |
| Narrow sudo permission for nginx reload | Sudo terminal/password error after the app starts | Persistent host permission | Deployments requiring that proxy command |
Verify the repair without guessing
- Keep trace mode enabled for one verification push and repeat the same Git command.
- Confirm the trace reaches the end of the deployment without a hook error and that Git reports the branch as accepted.
- Check that every declared process remains running rather than exiting immediately.
- Check application logs and Dokku process status for startup errors after the accepted push.
- Request the application through its normal hostname and confirm that nginx serves the new release.
- Turn trace mode off and retain the successful log with the failed log for future comparison.
If the push is still rejected, do not stack unrelated changes. Capture the new complete trace, identify the first changed error, and follow that phase. When opening a Dokku issue, include the full remote output with private keys, tokens, and other secrets removed; the final “pre-receive hook declined” line by itself cannot identify the fault.
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.
