# Troubleshooting

> Fix sign-in, MCP, session, repository indexing, usage, provider-key, team-invite, review and notification problems.

Start with the symptom that matches what you see. Make one change, then retry the action so you know which step fixed it.

## You cannot sign in

1. Open [app.fatelabs.ca](https://app.fatelabs.ca/dashboard).
2. If you signed up with Google, choose **Continue with Google** again rather than entering a password.
3. For email sign-in, use the same address you registered and confirm that address if your account is new.
4. If you forgot the password, choose **Forgot?** and complete the reset flow.

If a link sent you back to sign-in, sign in again without removing the original destination from the address so the interrupted flow can resume.

## Estelle's tools do not appear in your agent

1. Follow the [native host guide](https://docs.fatelabs.ca/install) for Claude Code, Codex, Kimi Code, Grok Build or Cursor. Confirm the package's actual registration and version; do not install the retired marketplace instructions over the current package.
2. Check that the actual host process can find external Node.js 22+ and inherits `ESTELLE_API_KEY`. A GUI app may have a different environment from your shell. Use the key-presence check in the install guide; never print the value.
3. Review native MCP and hook approvals, then reload or start a fresh session. For Codex, review `/hooks`; trust and enablement are separate. For Kimi, use interactive `/plugins info estelle` and `/reload`, not `kimi -p`.
4. Verify authentication with one advertised read-only MCP tool from the new session's catalogue. Do not invent an identity tool or keep repeating history reads as an authentication check. A registration or connection badge alone does not prove access.

If you configured hosted MCP without the native plugin, use that client's normal authentication or browser sign-in instead. A tools-only MCP connection does not install session capture. If you separately use the legacy CLI, `estelle doctor` can check that CLI setup; the CLI is not required for the native plugins.

## Sessions do not appear in the dashboard

- Confirm the dashboard and the host key belong to the intended account. Team session visibility can differ from the tool that created the entry.
- Check native hooks separately from MCP authentication, then inspect a new session's acknowledged entries. They prove those entries, not an unlimited transcript.
- Avoid duplicate legacy CLI hooks alongside a native plugin. Remove only verified old Estelle registrations after the replacement works; preserve unrelated hooks, chats, other hosts and shared memories.
- WSL instructions apply to the legacy CLI route, not every native plugin. A Windows host still needs external Node visible to its actual process.
- Choose **Show** for hidden older ended sessions. On a team, ask an admin or owner to inspect **Settings → Sessions & agent → Who can see sessions**.

## A repository sweep is refused or selects too much

Run a dry run from the repository root first:

```bash
estelle sweep --dry-run
```

This lists the files the sweep would send without sending them. A local sweep uses files git can see, so add build output, generated files and local secrets to `.gitignore` rather than deleting them only to make a sweep pass.

Then follow the refusal's reason:

- For missing usage, read the usage-limit steps below.
- For repository capacity, check the repository's status under **Settings → Connections → Choose what Estelle reads**.
- For GitHub access, confirm the Estelle App can see that repository, then choose **Recheck** in **Settings → Connections**.

## Estelle says “not swept” or “could not verify”

This means Estelle has no indexed evidence for that part of the repository. It does **not** prove that the code is absent or that the change is correct.

From a local checkout, run:

```bash
estelle sweep
```

For subsequent changes, `estelle reindex` updates changed files. From GitHub, sweep the repository again from **Settings → Connections**.

## Estelle says the index is stale

The repository moved after the last index. Sweep or reindex, then ask again. If an answer disagrees with a file you just edited, trust the file and refresh the index: uncommitted edits can be newer than the indexed version.

## You received a 402 or ran out of usage

A `402` means the account could not pay for that call. It is not an invalid-key error.

1. Open **Settings → Usage & limits** and read which limit stopped the work and when it recovers.
2. Wait for a rolling limit to recover, choose **Add more usage** if it is offered, or change plan in **Settings → Plans & billing**.
3. On Free, included usage does not renew. Choose a paid plan to continue using Estelle's inference after the grant is exhausted.
4. To use your own provider instead, add a key in **Settings → Provider keys** and select the surface it should serve.

Navigation and verification that only read the index can continue at a model-usage limit.

## A provider key or token fails its test

Choose **Test key** or **Test token** in **Settings → Provider keys** and read the provider's response.

- **Refused**: check the credential with the provider, then remove and replace it in Estelle. A workspace holds one key per provider.
- **Not confirmed**: the provider did not give a conclusive answer. Check its availability and try again.
- **Accepted, but the wrong model serves a surface**: open **Uses** and select that surface. Unticked surfaces stay on Estelle's own inference.
- **A custom provider is incomplete**: enter its endpoint URL as well as its key.
- **You cannot edit a shared key**: ask a team admin.

For Claude Code with a subscription, create a fresh token with `claude setup-token` on your own machine and add it as a **Claude subscription token**, not as an Estelle API key.

## A teammate cannot accept an invitation

1. Have them sign in or create an account with the exact invited email address.
2. Ask them to choose **Join**. Signing in alone never accepts the invitation.
3. If the emailed link expired or was already used, an admin chooses **Resend** to send a fresh link.
4. Check **Settings → Team** for seat and pending-invite capacity. A pending invite uses no seat; acceptance needs an available seat.
5. If the invite should no longer be valid, an admin can choose **Revoke**.

## Prism could not review a pull request

**Estelle couldn't review this yet** is not a finding against your change. The check is neutral rather than a clean review or a failure.

Push another commit or comment `/estelle review` to request another pass. If the cause was an outdated repository index, refresh the index and retry after it catches up. Read the check title before merging; neutral does not mean the review completed cleanly.

## Notifications are not arriving where you expect

Open **Settings → Notifications** and check both the event and channel:

- **In Estelle** is fixed on wherever offered, including a session waiting for input.
- **Slack** requires the team's Estelle channel for supported non-session events. Session details and links are withheld from shared Slack channels.
- **Email** is offered only for eligible pull-request and usage events. Session-linked email also requires current visibility; completed or failed sessions do not send outbound notices.
- Usage alerts use the levels and current plan period shown on the page, not the short rolling limits.

Notification rules are personal. Ask each teammate to check their own settings. Automation run receipts and webhooks are configured separately from this table.

## Get help

Contact us through [fatelabs.ca/contact](https://www.fatelabs.ca/contact). Include the command or workflow, what you expected, the exact error text and, for CLI or connection problems, the output of `estelle doctor`.

**Limit:**
Never include an Estelle API key, provider key, subscription token or repository secret. If a credential was exposed, revoke or replace it before continuing.

## Related

- [MCP server](https://docs.fatelabs.ca/mcp): Check endpoint and client setup.
- [CLI](https://docs.fatelabs.ca/cli): Review sweep, reindex, hooks and doctor commands.
- [Plans and credits](https://docs.fatelabs.ca/plans): Understand usage limits and plan changes.