---
title: "Troubleshooting"
url: "https://control.actana.ai/docs/install/troubleshooting"
description: "The usual install failures — PATH, bash 3.2, linger, unreachable ports — and their one-line fixes."
updated: 2026-09-01T09:03:02+00:00
---

Most install failures are one of these. `actana status` and `actana logs -n 200` are the first two commands.

## `actana` is not found in a new shell

The install links the launcher into `~/.local/bin`, which some distributions leave off `PATH` — and which a shell that started before the install will not have picked up. Add it:

```bash
export PATH="$HOME/.local/bin:$PATH"
```

This is why the installer prints an absolute path rather than a bare `actana` when `~/.local/bin` is not on your `PATH`. Running the line it printed always works.

## macOS: `asset…: unbound variable` from the one-liner

The stock macOS `bash` is 3.2, which mis-parses the installer where a variable is followed by a UTF-8 character (`say "Downloading $asset…"`). The download has not started; nothing is installed. Download the script and run it with a plain locale:

```bash
curl -fsSL https://raw.githubusercontent.com/actana/control/main/install.sh -o /tmp/actana-install.sh
LC_ALL=C bash /tmp/actana-install.sh            # add flags after, e.g. --version x.y.z-beta
```

This is a script bug, not something you did. A newer `bash` (`brew install bash`) removes the need for the locale override.

## The install finished and nothing is running

That is the install working. `install.sh` places the bundle and stops; [actana setup](/docs/install/actana-setup) is what makes this machine a Core. Run the line the installer printed. `actana status` before that says there is no Core installed for this user, which is true until setup has run.

## It said it left the launcher alone

Something else already answers to `actana` — usually `npm i -g @actana/cli`, whose global shim lands in the same directory. Nothing is broken: it is the same program (one `actana`), so it runs this Core's `status`, `logs` and `update` as well. The message names where this install's own launcher is, and the `actana setup` command it prints goes through that launcher. To hand the path over, remove the other install (`npm rm -g @actana/cli`) and re-run the install.

## The service started but nothing is listening

```bash
actana logs -n 200
```

A port already in use and an unreachable `--public-host` are the two common causes.

## The daemon stops when I log out

**On macOS this is expected.** A LaunchAgent stops at logout and comes back at your next login. Keep the session logged in (System Settings → Users & Groups → Automatic login) if the Core has to stay reachable. See [Linux and macOS](/docs/install/install-core).

**On Linux** it means lingering is not enabled — `actana status` reports this on its `Linger` row.

```bash
loginctl enable-linger "$(whoami)" && actana restart
```

If your distribution refuses that for a normal user:

```bash
sudo loginctl enable-linger "$(whoami)"
```

## The Core is unreachable from the Panel

The Panel dials the Core. Check each layer: is the daemon listening (`ss -tlnp | grep 8443` on Linux, `lsof -iTCP:8443 -sTCP:LISTEN` on macOS), is the service active (`actana status`), is the firewall open (`sudo ufw status`, or System Settings → Network → Firewall), and can the Panel machine reach the port (`nc -zv <public-host> 8443`)?

If the machine's address changed since setup, the certificate no longer covers it. Re-run setup and pair again with a fresh code:

```bash
actana setup --public-host <new-address>
actana pair new
```

## `getaddrinfo ENOTFOUND host.docker.internal` when pairing

A CLI running **on the host** cannot resolve that name — it exists only **inside** containers, where Docker Desktop points it at the host. Dial the name that routes from where you are: on the Core's own host with the port published, that is `localhost:8443`, and `localhost` must be an entry of `ACTANA_PUBLIC_HOST` so the certificate covers it. The dial-address table is in [Pair from the CLI](/docs/pairing/cli-pairing).

## See also

- [Install in one command](/docs/install/install-core)
- [actana setup](/docs/install/actana-setup)
- [Linux and macOS](/docs/install/install-core)
- [Pairing troubleshooting](/docs/pairing/troubleshooting)