## TL;DR

ERR_NGROK_6022 means the ngrok agent started without a valid authtoken, so it cannot open a tunnel session. Sign up at the ngrok dashboard, copy your authtoken, and install it with `ngrok config add-authtoken`. If the error persists after that, the token went into a config file your binary is not reading (old vs new config locations), or another session is already using your free-plan slot.

### Verbatim error

```text
ERR_NGROK_6022
```

(Full text from the ngrok docs: "Before you can serve HTML content, you must sign up for an ngrok account and install your authtoken.")

## When this applies

- `ngrok http` (or any tunnel command) exits immediately with ERR_NGROK_6022.
- You never installed an authtoken, or you reinstalled ngrok and the config was wiped.
- A framework (Shopify CLI, Atlassian ACE, an npm ngrok wrapper) launches its own bundled ngrok binary.

## When this does NOT apply

- Tunnels start but drop or reconnect: that is a network or session-stability problem, not 6022.
- `ERR_NGROK_3200` or endpoint-pool errors: those are about tunnel URL configuration, not authentication.
- The error appears in a browser as `ERR_TUNNEL_CONNECTION_FAILED`: that is a Chrome proxy error, unrelated to ngrok.

## Fix

### 1. Install your authtoken

Get the token from the ngrok dashboard, then run:

```bash
ngrok config add-authtoken [your authtoken]
```

Expected output: `Authtoken saved to configuration file`. Then start your tunnel again.

### 2. Confirm the token landed in the file your binary reads

Newer ngrok versions read the config from your user config directory (`ngrok.yml` under it); older ones read `~/.ngrok2/ngrok.yml`. If you have two ngrok binaries (a global install plus one bundled inside `node_modules`), each may read a different location. Check which binary runs and verify its config file contains the token -

```bash
which ngrok
ngrok config check
```

Expected output: one binary path, and the check reports a valid configuration. If the token is in the wrong file, copy it to the location your binary reads and restart.

### 3. Free-plan session conflicts

Free ngrok accounts allow one agent session at a time. If another machine or process holds a session, new tunnels fail. Check the ngrok dashboard for active sessions and stop the stale one.

Expected output: the dashboard shows no other active agent session; your tunnel starts.

### 4. Retry the tunnel

```bash
ngrok http 8080
```

Expected output: a `Forwarding` URL line instead of ERR_NGROK_6022.

## Variant phrasings

### ngrok tunnel could not be started
Often the same root cause when the underlying error is 6022; check the full error output for the code.

### ERR_NGROK_6022 after reinstalling ngrok
Reinstalls wipe the config file. Re-run step 1; the dashboard token is unchanged.

## Why it happens

Every ngrok tunnel session must authenticate to the ngrok service with your account's authtoken. Without it the agent cannot register the session, so it exits with 6022 before any tunnel is attempted. The classic trap is multiple binaries: the token gets saved for one binary's config location while the framework launches another.

## Edge cases

- CI or agent shells: set the token non-interactively with the same `config add-authtoken` command before launching the tunnel; never paste the token into chat logs.
- Docker: bake the token into the container's ngrok config or pass it at container start, not into image layers you share.
- Rotated tokens: if you reset the token on the dashboard, every machine using the old one gets 6022 until updated.

## Tool compatibility

ngrok agent v2 and v3. `config add-authtoken` is the v3 command; v2 uses `ngrok authtoken`. Dashboard and session limits as of the current ngrok pricing.