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 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 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.
- 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 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. 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:
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.
The connector
With Docker:
docker exec localcan-connector /localcan connector status
docker logs localcan-connector
With systemd:
sudo -u localcan env LOCALCAN_HOME=/var/lib/localcan-connector localcan connector status
journalctl -u localcan-connector
A healthy connector looks like this:
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.
© 2026 LocalCan™. All rights reserved.