# Troubleshooting

###### When an app behind LocalCan Access doesn't open, the answer is usually in one of three places: the page the person sees, the connector's status on your server, or the app's Domain section in the dashboard.

#### A TLS or certificate error on the hostname

LocalCan gets the hostname's certificate from Let's Encrypt once the CNAME resolves and the connector is connected. Until then, browsers show a TLS error. Right after you switch the CNAME, that lasts a few minutes. If it lasts longer:

- Check that the CNAME chain ends exactly at the **CNAME target** the app's Domain section shows. An A or AAAA record at the hostname doesn't work.
- Check that the [connector](#the-connector) is running and reports `active`.
- While the CNAME doesn't resolve to the target, the connector's status shows `Could not verify your CNAME. Check your DNS provider and try again.` The connector checks again after a minute, then less often, up to every 5 minutes. A fixed CNAME is picked up on its own.

An app whose hostname never gets a certificate is removed 14 days after you created it. Add it again once the DNS record is ready.

#### LocalCan error pages

| Code | Page title | What it means |
| --- | --- | --- |
| LC2001 | Sign-in is temporarily unavailable | LocalCan couldn't check the sign-in. It recovers on its own. People already signed in keep working for up to 60 minutes after their last successful check. |
| LC2002 | Sign-in didn't complete | The sign-in link expired or was used already. **Continue** starts again. If it keeps happening, check who the app allows. |
| LC2003 | This app isn't ready yet | Sign-in for the app isn't set up on the LocalCan server yet. If it lasts, check the app in the dashboard. |
| LC2004 | Service token not accepted | The [service token](/docs/access/service-tokens-and-mcp) is wrong, revoked, expired, or doesn't cover this app. |
| LC2005 | Too many sign-in attempts | One network started too many sign-ins in a short time. Wait a minute, then select **Continue**. |
| LC2006 | This app isn't served here | The hostname reached a LocalCan server that doesn't serve the app. Check the CNAME and that the connector is running. |

An **Access suspended** page means the app is turned off or deleted, the team no longer has LocalCan Access, or the team's LocalCan account is suspended.

#### Nobody can sign in

- The app has no rule yet. A new app lets nobody in until you add one under **Who may sign in**.
- The team doesn't have LocalCan Access, for example after its preview ended. Apps are set up but let nobody in until the team owner adds it under **Billing**, and the **Apps** page shows them as **Blocked**.
- The person's address doesn't count for their sign-in method, for example a Google account made with a non-Gmail address. See [which email counts](/docs/access/sign-in-methods#sign-in-methods).
- The person is blocked. Check **LocalCan Access → People**.

#### "Your organization must approve LocalCan Access"

The person's Microsoft organization lets only admins approve new apps. See [Microsoft](/docs/access/sign-in-methods#microsoft) for the address an admin uses to approve LocalCan Access for everyone.

#### "Finish signing in in the same browser you started in"

The sign-in started in another browser or browser profile, for example when a chat app opened the link in its own browser. Open the app again in the browser you want to use.

#### Grafana still asks people to log in

Check the `[auth.jwt]` settings and that `root_url` is the app's address, as in [Grafana](/docs/access/identity-header#grafana). Metabase, Umami and n8n keep their own login by design.

#### Scripts get a 401 with JSON

A request that isn't a page load, such as `fetch` or `curl`, gets this instead of a redirect to sign-in:

```plaintext
HTTP/2 401
content-type: application/json
www-authenticate: LocalCan-Access
x-localcan-auth: login

{"error":"authentication_required","login":"/.localcan/access/login"}
```

Give the script a [service token](/docs/access/service-tokens-and-mcp).

#### The connector

With Docker:

```bash
docker exec localcan-connector /localcan connector status
docker logs localcan-connector
```

With systemd:

```bash
sudo -u localcan env LOCALCAN_HOME=/var/lib/localcan-connector localcan connector status
journalctl -u localcan-connector
```

A healthy connector looks like this:

```plaintext
State:     active
Instance:  3f9c1a7e5b2d8046
Key from:  LOCALCAN_CONNECTOR_KEY_FILE

  metabase.example.com                     connected    upstream ok
```

| State | What it means and what to do |
| --- | --- |
| `active` | Connected. Each app line shows its tunnel and whether the upstream answers. |
| `starting` | Connecting to LocalCan. |
| `replaced` | Another connector started with the same key and took over. The newest one always wins, and this one stays idle, so restart policies don't start a tug of war. Its status usually names the host and IP address that took over (a Docker connector's host is its container ID, unless you set `--hostname`). If you moved the connector on purpose, stop this one. If you didn't start the other one, select **Rotate key** in the connector's menu on the **Connectors** page. |
| `revoked` | LocalCan doesn't accept the key: it was rotated, or the connector was deleted. Start the connector with its current key. It checks again every 5 minutes. |

When another connector takes over, the team's owners and admins also get an email naming the new server's IP address, and for 7 days the **Connectors** page shows an amber icon next to the connector's status. Its tooltip names the server it replaced and the one that took over. A connector that comes back from a new IP address, for example after its server's address changed, counts as a takeover too.

If the command prints `The connector is not running.`, it couldn't reach the connector. Check `docker ps` or `systemctl status localcan-connector`.

#### "This is a LocalCan Access connector key"

A connector key works only with the connector. The `localcan license activate` command refuses it with this message, and the LocalCan desktop app says `License key is not valid`. Use your own license key there.

#### The LocalCan Access pages are read-only

Changes to LocalCan Access need an owner or admin account with two-factor sign-in. Without it, the pages are read-only and a banner says so. Turn two-factor sign-in on under **Account Settings → Security**. If a save asks you to sign out and sign in again, do that, then save again.

