> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orchestrahq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting Orchestra Local

> What each Local problem looks like, the doctor or share log line that finds it, and the command that fixes it

Start with two commands. Both only read, and both name the fix for what they
find:

```bash theme={null}
orchestra doctor        # every check: the daemon, hooks, sign-in, sharing, each repository's host
orchestra share log     # what sharing did on this computer, in order, with the reason for anything held or failed
```

The desktop app's **Sharing** screen shows the same publishing state for each
repository. For problems with a team (a teammate missing, the team key), see
[If something is not right](https://docs.orchestrahq.ai/local-teams.md#if-something-is-not-right) on the
team page.

## Nothing is publishing

| What you see | What finds it | What to do |
| - | - | - |
| Teammates never see your sessions | `orchestra doctor`: `sharing: <repo> ...` for each repository, saying whether it publishes and why not | Do what the line says: say yes with `orchestra session consent yes`, ask the admin who turned it off, or move the repository out of Personal. Then `orchestra session publish --missed` sends the ended sessions that never went out. |
| A session was held back | `orchestra share log` shows `held` with the reason; `orchestra session shared` lists every held session | Private sessions are held on purpose. For a secret, review it as the line says. Publish one by hand with `orchestra session publish <id>`. |
| Publishing failed | `orchestra share log` shows `failed` with the reason. After an hour, `orchestra doctor` says so too | Read the reason: a network or sign-in problem clears on its own at the next session's end. The next three rows cover the others. |
| `The remote refused refs/orchestra/...` | `orchestra share log`, with the host's own words (for example GitHub's `GH013: Repository rule violations`); `orchestra doctor` checks each repository's host too | Your host allows only branches and tags. Ask for `refs/orchestra/*` to be allowed, or set a [memory repo](https://docs.orchestrahq.ai/local-how-it-works.md#a-memory-repo-for-the-whole-team). |
| `This session has N events and is X MiB ... over the 2 MiB cap` | `orchestra share log` and `orchestra session shared` | A very long session stays on your computer. |
| `Session <id> is not saved on this computer, so it was not published` | The terminal, and `orchestra share log` | It was taken off the record, saved in another workspace, or never captured here. Nothing to fix. |

## Agents work without Orchestra

| What you see | What finds it | What to do |
| - | - | - |
| Agents stop getting memories at the start of a task, or the session list misses sessions | `orchestra doctor`: `hooks ran out of time and stood down N times in the last 7 days (...)` | Hooks give up quickly rather than hold your agent up. Something on this computer is slow: the Local daemon starting, git in a very large repository, or a busy disk. `orchestra local status` shows the daemon. If it keeps happening, send the `orchestra doctor` output to [support@orchestrahq.ai](mailto:support@orchestrahq.ai). |
| `Orchestra hook(s) here have an old time limit` | `orchestra doctor` | Run `orchestra enable` in the repository again. |
| Codex sessions get no memories | `orchestra doctor` | Run `/hooks` in Codex once and trust the hooks `orchestra enable` wrote. |
| `Local daemon is not answering` | `orchestra doctor`, `orchestra local status` | `orchestra local start`. |

## Teammates' sessions look wrong

| What you see | What finds it | What to do |
| - | - | - |
| A teammate's finished session shows as running | The Sessions list, under the team | Their computer may be offline: a session not heard from shows as offline, then ended once their computer says so. An ended session only shows as live again when it has new activity. |
| A session reads **Left open** | The Sessions list | The agent is still open but nothing has happened for a while. It is not ended. |
| A team shows sessions from another team's repositories | The Sessions list | Each team shows only its own repositories. If one appears in two teams, the repository is in both teams' workspaces on that computer: see [Several workspaces](https://docs.orchestrahq.ai/several-workspaces.md). |
| `teammates' sessions ... could not read: <repo>` | `orchestra share log` (`fetched` lines) | You cannot read that repository's remote with your git credentials, or you are offline. `git ls-remote origin` in that repository shows the git error. |

## Windows and WSL

| What you see | What finds it | What to do |
| - | - | - |
| Sessions from Git Bash, MSYS2 or Cygwin are missing from the desktop app | `orchestra local status` in that shell and in PowerShell name different folders | Orchestra keeps its state in your user profile, where the desktop app and the login item look. A shell whose `HOME` names another folder still uses the profile, unless Orchestra was first set up under that `HOME`. In that case, set `HOME` to your profile in that shell's startup file. |
| A repository on a network drive or UNC path is held back | `orchestra doctor`, `orchestra share log` | Other people may read a network share, so sessions there wait for a yes. A team admin allows it with `allow_local_readers = true` in the repository's `.orchestra/config.toml`. |
| WSL and Windows on the same checkout | `orchestra doctor` on each side | Supported. Each side keeps its own state. Commits from either side keep working. |

## Still stuck

Send the output of `orchestra doctor` and the last lines of `orchestra share log`
to [support@orchestrahq.ai](mailto:support@orchestrahq.ai). Read them first: they name your repositories.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.