# Troubleshooting and FAQ

Fixes for the problems people meet most: pairing, sign-in, harnesses, the runner, desktop updates, the network and paused features.

Find the message you see, then follow its fix. If none fits, write to `hello@easycode.studio`.

## Sign-in and pairing

### The desktop app's sign-in code fails

The desktop app signs you in through your browser: it opens **Sign in a device** with a code to approve.

- **This code is unknown or has expired**: the code lived too long. Start sign-in again from the desktop app and
  approve the new code straight away.
- **This code was already used**: the device is signed in, or another tab approved it. Go back to the desktop app.

If the browser page never opens, check that your network allows EasyCode's hosts:
[Network and firewall](/setup/network-and-firewall).

### The local app says "Open EasyCode from your terminal"

The local app runs commands and edits files as you, so it opens only in a browser you paired with it. Start it from
a terminal; it opens the pairing link for you:

```bash
easycode dev
```

**That pairing link is not valid for this machine** means the link is old or from another launch. Each launch makes
a new one. Use the link the latest launch printed. **Settings → Access & pairing** lists the browsers that can use
the app.

## Harnesses

**Settings → Harnesses** shows each harness's state as a badge.

### Not installed

The app didn't find the harness's command. Click **Install** to run its install command in a terminal below, or
install it yourself. Each harness's command is in the [harness reference](/reference/harnesses).

> **Desktop app only**
>
> When you start the desktop app from the Dock or the Start menu, it reads your PATH from your login shell, so tools
> installed with Homebrew, nvm or volta are found. If you install a harness while the app is open, quit and reopen it.
> **Settings → Desktop** shows how this launch found your PATH.

### Signed out or Expired

The harness is installed but has no valid login. Click **Connect**; it runs the harness's own sign-in command in a
terminal, and you sign in with the vendor. EasyCode never sees the login. An **Expired** badge may say when it
checks again.

### Needs update

The installed version is older than the version EasyCode needs. Click **Update**.

## The runner

### The runner is not answering

The runner is the local process that drives your harnesses. When it is down, harness cards show **Runner down** and
sessions can't start.

**Desktop app**

The desktop app restarts a runner that stops on its own a few times. If it stays down, quit EasyCode and open it
again. **Settings → Diagnostics** shows what the runner counted.

**Local app**

Start the app again with `easycode dev`, or only the runner with `easycode runner`.

## Desktop updates

**Settings → Desktop** shows the update state. **Check for updates** asks now; **Retry** follows an error.

- **Restart to update** waits while sessions are running, then installs once they finish.
- **A required update**: when your org needs a newer version, the update banner says so. Install it; an older
  version stops working with your org once the requirement starts.
- **Your system has no keyring, so your sign-in is stored with weak protection**: this Linux desktop has no keyring
  service, so the app can't use the OS's secure storage. Run it on a desktop with a keyring service for full
  protection.

### Unsigned builds

Pilot builds may be unsigned, marked **Unsigned alpha** or **Unsigned beta** on the download page. Updates then
install by hand, and the app guides you:

**macOS**

The app downloads the update, checks it, and opens the disk image. Drag EasyCode to Applications and replace the old
one, then open it again.

**Windows**

The first install from a browser shows **Windows protected your PC**: choose **More info**, then **Run anyway**.
Updates the app downloads itself don't ask. Where Smart App Control is on, Windows blocks unsigned apps.

**Linux**

An AppImage replaces itself and relaunches. A `.deb` install opens the download page, where you get the new `.deb`
and install it with your package manager.

More in [Desktop app](/setup/desktop-app).

## Network

Sign-in, sync, updates or the studio fail behind a company firewall or proxy? Your network must allow EasyCode's
hosts. [Network and firewall](/setup/network-and-firewall) lists them.

## Something is off or paused

Some messages mean a part of EasyCode is turned off for your org, not that something broke.

- **Knowledge is off for** your org, **The library is off for** your org, **Board isn't enabled for** your org, or a
  rail item missing: that module is off for your org. Ask an org admin; if you are the admin, ask your EasyCode
  contact to turn the module on.
- **Pick-up is paused by EasyCode**, **The Board is paused**, **This is switched off for now**, **Knowledge runs are
  switched off for now**, **publishing is switched off for this org**: a kill switch is off for now. It isn't
  something you can fix; work resumes when it is back on.

[Kill switches and modules](/reference/kill-switches-and-modules) lists each one and what it pauses.

## FAQ

### Why can't I read a teammate's session?

You see a teammate's session title and status when you can see its product. To read its content or pick it up, all
of these must hold: it isn't **Private**, your org has session content on, you are a contributor or maintainer on its
product, and you can read its repo on GitHub. A session with no product is its owner's alone.
[Roles and access](/overview/roles-and-access#sessions).

### Can I start a session from the web app?

No. The web app runs no harness. Start sessions from the desktop app, and follow them from either.

### Does EasyCode store my harness login?

No. Each harness signs in on your machine and keeps its own credentials. EasyCode never reads them.
[Security and privacy](/overview/security-and-privacy).

### Does my code train a model?

EasyCode trains no models. Your harness vendor's terms apply to what you send them.

### Which harnesses work?

Claude Code, Codex, Cursor, Copilot, Gemini, OpenCode and pi. See [the harness reference](/reference/harnesses)
for support levels and tested versions.
