// 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
Share

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

  1. FIX 1Verify the port mapping

    1. 01Run docker port <container> or check your compose ports section
    2. 02Make sure the host port in your clone URL maps to the container's SSH port
    3. 03Fix the mapping and recreate the container
    Did this fix it?
  2. FIX 2Add and use the right key

    1. 01In Gitea go to Settings > SSH / GPG Keys and add your public key
    2. 02Use the user git, for example ssh://git@host:2222/user/repo.git
    Did this fix it?
  3. FIX 3Debug the connection

    1. 01Run ssh -vvv -p 2222 git@host
    2. 02Read Gitea container logs for Invalid user or key errors
    3. 03Open the port in ufw or iptables
    Did this fix it?
  4. FIX 4Force the correct key on the client

    1. 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 us

Watch Gitea Get an email when its price changes, it has an outage, or we publish a new fix. No spam.

Fixed it? Share this guide

The same problem in other apps

All not loading, error messages & connection guides →

Other Gitea errors

All 11 Gitea errors and fixes →