---
title: "Troubleshooting"
description: "Fixes for common problems with the install, logins, domains, updates and servers."
canonical_url: "https://harblet.com/docs/reference/troubleshooting"
---
# Troubleshooting

> Fixes for common problems with the install, logins, domains, updates and servers.

Most problems show a message in Harblet that says what to do. This page covers the cases where you need the server's command line. Run the commands on the **first server**.

## The install script stops

<table>
<thead>
  <tr>
    <th>
      Message
    </th>
    
    <th>
      What to do
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      k3s is already installed on this server, so Harblet can't be installed.
    </td>
    
    <td>
      Use a fresh server, or remove k3s with <code>
        sudo /usr/local/bin/k3s-uninstall.sh
      </code>
      
       first. This deletes everything k3s ran.
    </td>
  </tr>
  
  <tr>
    <td>
      This server's IPv4 address couldn't be found.
    </td>
    
    <td>
      Set <code>
        HARBLET_URL
      </code>
      
      , see <a href="https://harblet.com/docs/getting-started/installation#servers-behind-nat">
        Servers behind NAT
      </a>
      
      .
    </td>
  </tr>
  
  <tr>
    <td>
      k3s didn't become ready within 5 minutes.
    </td>
    
    <td>
      Check that the server meets the <a href="https://harblet.com/docs/getting-started/installation#requirements">
        requirements
      </a>
      
      , then start over.
    </td>
  </tr>
  
  <tr>
    <td>
      Installing Harblet failed. To start over, run /usr/local/bin/k3s-uninstall.sh and then this script again.
    </td>
    
    <td>
      Run <code>
        sudo /usr/local/bin/k3s-uninstall.sh
      </code>
      
      , fix the cause shown above the message, and run the install command again.
    </td>
  </tr>
</tbody>
</table>

## Logins are rejected

Harblet accepts logins only at its own address: the one the install script printed, or `https://<domain>` once Harblet has [its own domain](https://harblet.com/docs/administration/harblet-domain). Open Harblet at exactly that address.

If your browser can't reach that address, for example because the server is behind NAT, set the address Harblet runs at:

```bash [First server]
sudo k3s kubectl -n harblet-system set env deployment/harblet -c harblet NUXT_PUBLIC_SITE_URL=http://203.0.113.10:3000
```

Harblet restarts with the new address within seconds.

## Harblet isn't reachable at its domain

If you saved a wrong domain under **Settings** → **General**, or its DNS or certificate doesn't work, either fix the DNS record, or move Harblet back to its IP address with the command above. Then log in at `http://<ip>:3000` and set the domain again.

Port 3000 has to be open for this. If you closed it in your firewall, open it again first.

## An update doesn't start

If a new version of Harblet doesn't come up after an update, switch back to the version you had before:

```bash [First server]
sudo k3s kubectl -n harblet-system set image deployment/harblet harblet=ghcr.io/harblet/harblet:<old version>
```

<warning>

This only works if the new version hasn't changed Harblet's database in a way the old version can't read. If it has, restore your [backup of Harblet](https://harblet.com/docs/backups/harblet-backups) instead.

</warning>

## A k3s upgrade is stuck

The [Servers](https://harblet.com/docs/administration/servers) page shows **The k3s upgrade is stuck** with Kubernetes' message, or a server shows **Upgrading to** for a long time.

- If the message says an image can't be pulled, check that the server can reach the internet. Kubernetes keeps trying by itself.
- If you went back to an older Harblet that shouldn't upgrade k3s anymore, stop the upgrade:

```bash [First server]
sudo k3s kubectl -n harblet-system delete plans --all
```

## Services don't start after a reboot

Image services and databases ask their registry for their image every time they start, for example Docker Hub. If the registry can't be reached right after a reboot, they stay down until it can. They start by themselves once the server is online again. Services built from Git start from the image on the server.

## The first build fails right after the install or a reboot

Right after k3s starts, the cluster's DNS may not answer yet, and the clone step of a build fails. Click **Deploy** again a minute later.

## A removed server doesn't boot completely

A server you [removed](https://harblet.com/docs/administration/servers#remove-a-server) keeps trying to reconnect until you uninstall the k3s agent on it. Log in over SSH and run:

```bash [Removed server]
sudo /usr/local/bin/k3s-agent-uninstall.sh
```

## Someone forgot their password

Harblet has no password reset yet. An admin removes the member under **Members** and [invites them again](https://harblet.com/docs/administration/team#invite-a-colleague). Their deployments stay.

## Get help

Look for an existing issue or open a new one on [GitHub](https://github.com/harblet/harblet/issues), or write to [mail@harblet.com](mailto:mail@harblet.com).


## Sitemap

See the full [sitemap](https://harblet.com/sitemap.md) for all pages.