// troubleshooting guide · gitea
Gitea SSH Permission Denied (publickey) or Connection Refused
- Status
- Workaround available
- platforms:
- Docker, Linux, any client
- updated:
- November 16, 2026
- reports:
- 4
- Method
- how we research
RUNBOOK · gitea/ssh-permission-denied4 FIXES
// quick answer
Usually the wrong SSH port in the clone URL, the key not added to your account, or a username other than git. Test with ssh -vvv.
Most likely fix: Verify the port mapping
How to fix it
// try these in order, the most common fix is first
FIX 1Verify the port mapping
- 01Run docker port <container> or check your compose ports section
- 02Make sure the host port in your clone URL maps to the container's SSH port
- 03Fix the mapping and recreate the container
Did this fix it?FIX 2Add and use the right key
- 01In Gitea go to Settings > SSH / GPG Keys and add your public key
- 02Use the user git, for example ssh://git@host:2222/user/repo.git
Did this fix it?FIX 3Debug the connection
- 01Run ssh -vvv -p 2222 git@host
- 02Read Gitea container logs for Invalid user or key errors
- 03Open the port in ufw or iptables
Did this fix it?FIX 4Force the correct key on the client
- 01In ~/.ssh/config add Host, HostName, Port, User git, IdentityFile and IdentitiesOnly yes
Did this fix it?
SANDBOX · gitea RUNS IN YOUR BROWSER
Try it: push, review, run CI and merge in a code host and cloud workspace
A hands-on Gitea-style sandbox, including the spots where users get stuck. See where problems like this one start. 1-2 minutes, nothing is saved.
Symptoms
git clone or push over SSH fails with Permission denied (publickey) or Connection refused, often with Gitea in Docker.
Why it happens
- C-01Host port mapping does not match the port in the clone URL
- C-02SSH key not added to the Gitea user account
- C-03Username used is not git (container logs show Invalid user)
- C-04Firewall blocks the port
- C-05Reverse proxy such as Traefik in front of SSH
- C-06Client offering the wrong key
// this guide also covers
- gitea ssh permission denied publickey
- gitea ssh connection refused docker
- gitea clone ssh fails
Still not working?
If Gitea keeps failing, you're not alone. See every Gitea problem users report or the alternatives people switch to.
Have an app idea? Our small team builds any software: web and mobile apps, games, desktop, AI tools. Price agreed together.
Talk to usThe same problem in other apps
Other Gitea errors
- Gitea Actions Jobs Stuck in Waiting (No Matching Runner)
- Gitea 500 Internal Server Error
- Gitea Reverse Proxy Wrong URLs or Redirect Loop (ROOT_URL)
- Gitea Push 413 Request Entity Too Large (LFS Upload Fails)
- Gitea Webhook Not Working (ALLOWED_HOST_LIST Error)
- Gitea Email Notifications Not Sending (SMTP Error)
- Why Is Gitea Using So Much Memory or CPU?
- Gitea Upgrade Failed or Database Is Locked