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

# Fix common problems

Start with these two commands. Most problems show up in one of them.

```sh
haarness doctor          # version, bundled tools and where your data is
haarness logs --tail 50  # the end of the newest log file
```

`haarness logs` without `--tail` lists the log files and their folder. `haarness --update` installs
the latest release (the terminal UI's home screen says when one is out); the `haarness` that comes
with Haarness Desktop updates with Desktop instead.

## Get more detail in the logs

```sh
haarness --log-level debug run "…"
```

Logs are always written to the log folder. `--print-logs` also prints them to the terminal. In
the terminal UI that garbles the screen, so send them to a file:

```sh
haarness --log-level debug --print-logs 2>/tmp/haarness.log
```

To make the Haarness servers and apps that are already running log more, without restarting
them:

```sh
haarness logs level debug           # for 30 minutes; --for 2h, or --until-stopped
haarness logs level stop            # back to normal
```

In Desktop, this is **Detailed logging** in **Settings → General**; in the terminal UI,
`/logs detail`.

## Send your logs with a bug report

```sh
haarness logs export
```

This packs the log files into `haarness-logs-<time>.zip` in the current folder, with tokens,
passwords, keys and other known secret shapes replaced by `[redacted]`. Text you typed or a tool
printed can still contain a secret, and paths and host names stay, so look through it before you
send it. In Desktop, use **Settings → General → Diagnostics → Export logs…** or
**Help → Export logs…**; in the terminal UI, `/logs export`.

## The model I picked is rejected

```sh
haarness models             # the models you can use right now
haarness models openai      # one provider
haarness providers          # which providers are connected
```

Haarness asks each connected provider which models your credentials can use. If the provider is
missing from `haarness providers` or not connected, sign in with `haarness auth login <provider>`;
see [Connect a provider](https://haarness.ai/docs/start/connect-a-provider.md). With a ChatGPT sign-in, a model your plan
does not include is refused before the request, and the message lists the ones you can use.

## `haarness run` uses the wrong model

Without `-m`, `haarness run` starts a new chat on your default model: the `model` in your
[configuration](https://haarness.ai/docs/cli/configuration.md#set-your-default-model), or else one from a provider you
connected. `--continue` and `--thread` keep the chat's own model. Pass `-m provider/model` to
choose; `haarness models` lists the names.

## A request to the provider failed

The error in the chat names the provider and gives its own message, not just a status code. It
usually says what is wrong: an expired key, a usage limit, or a model you cannot use. A provider
that cannot be reached is named with its address. Check the connection with
`haarness providers`, and connect it again if the key was refused.

## The agent cannot use a tool

In the terminal UI, `/tools` lists every tool and whether it is on. A tool can be turned off in
`tool_availability` in your [configuration](https://haarness.ai/docs/cli/configuration.md), or removed for one
[agent](https://haarness.ai/docs/cli/agents-commands-skills.md) with `--tool name=false`. A permission rule set to
`deny` also blocks it; see [Permissions](https://haarness.ai/docs/security/permissions.md).

## A turn seems stuck

- **It may be waiting for your approval.** Look for a permission prompt in the chat.
- **In Auto, it may show Reviewing…** while a reviewer model checks a request. If the reviewer has
  not decided within 60 seconds, the request comes to you instead.
- **`haarness run` stopped with "nobody can approve that in this run".** In a script or CI there
  is nobody to answer, so the request was refused. Allow what it needs in your permission rules,
  or pass `--yolo`. See
  [Run a prompt from a script or CI](https://haarness.ai/docs/cli/headless-runs.md#handle-permission-prompts-in-ci).
- **To stop it,** type `/cancel`, or press `Esc` twice. `Ctrl+C` clears your draft first, then
  stops the turn.
- **For helpers the agent started,** `/tasks` lists them and opens their chats.

## A tool call says "Stopped by Auto's reviewer"

In a chat in Auto, a reviewer model refused that request and told the agent why. Nothing ran. If
you want it done, switch the chat to Review (`Ctrl+Y` in the terminal UI) and ask the agent to try
again; this time the request comes to you. To stop the reviewer refusing that kind of request, say
what is fine in your [settings](https://haarness.ai/docs/security/permissions.md#tune-the-reviewer-or-turn-it-off).

## I closed the terminal. Is my turn still running?

Yes. Closing the terminal UI does not stop a turn; it keeps running on the Haarness server for
that folder. Open the folder again with `haarness --continue` to see it. If you quit with
Ctrl+D or `/exit`, the terminal UI printed the exact command to reopen that chat.

If the server stops while the terminal UI that started it is still open, the terminal UI starts
it again by itself, and the status line says **server stopped · restarting it**.

To stop everything in that folder, run:

```sh
haarness serve --stop
```

This also ends any turn or workflow that is still running.

## After a crash

Your chats are kept. Haarness does not re-run commands or file edits that were in progress; they
are marked as interrupted. A workflow that was running is marked `interrupted`, and
`haarness workflow resume <run-id>` starts it again from the beginning. A goal that was active
comes back paused.

## A language server or formatter is missing

The chat carries on without it. `/status` in the terminal UI shows each language server and
formatter, and which ones are missing. Install the program, or turn it off in your
[configuration](https://haarness.ai/docs/cli/configuration.md#language-servers-and-formatters).

## A project's settings cause the problem

Start without them:

```sh
haarness --disable-project-config
```

This ignores the project's settings, instructions, commands, agents, skills, MCP servers,
workflows, plugins and extensions, and keeps yours.

## Chrome does not connect

```sh
haarness browser status   # is Chrome set up, and which projects does it reach?
haarness browser setup    # set it up again
```

- **The Haarness button in Chrome says Not set up.** Run `haarness browser setup` again, then
  check that **Haarness** is on at `chrome://extensions` and **Developer mode** is still on.
- **Chrome is connected, but the agent says it is not.** The project's Haarness server may be
  older than the extension. When its work has finished, run `haarness serve --stop` in that
  project and open it again.
- **A work or school Chrome** may block it by policy: see `chrome://policy`.
- **Chrome from Flatpak or Snap** cannot start Haarness; `haarness browser status` says so.
- **A project on another computer** cannot use your Chrome yet.

More causes and fixes are in
[Use your Chrome](https://haarness.ai/docs/desktop/use-your-chrome.md#chrome-does-not-connect).

## Where Haarness keeps its files

| What | Default folder | Change it with |
| --- | --- | --- |
| Settings (`haarness.json`, the terminal UI's `config.toml`), agents, commands, skills, workflows | `~/.config/haarness/` | `XDG_CONFIG_HOME` |
| Chats, credentials, logs | `~/.local/share/haarness/` | `XDG_DATA_HOME` |
| Caches and running servers | `~/.cache/haarness/` | `XDG_CACHE_HOME` |
| Haarness for Chrome: its helper and the extension folder you load | `~/.local/share/haarness/browser/chrome/` | `XDG_DATA_HOME` |

These defaults apply on macOS and Windows too, with a few exceptions. On macOS, these still live
in `~/Library/Application Support/dev.haarness.haarness/`:

- schedules and their logs
- saved output of long commands
- Canvas preview versions from Desktop

On Windows, the same things live in `%APPDATA%\haarness\haarness\` and
`%LOCALAPPDATA%\haarness\haarness\`.

Set `HAARNESS_HOME` to an absolute folder to move all of it, exceptions included, under one place:
`config/`, `data/`, `cache/` and `state/` inside it. Your Haarness Cloud sign-in is kept in
`~/.config/haarness-cloud/`, or in `config/account/` inside `HAARNESS_HOME`.

On macOS, terminal UI settings that an older version kept in
`~/Library/Application Support/dev.haarness.haarness/config.toml` still apply until
`~/.config/haarness/config.toml` sets them.

## Related

- [Configure Haarness](https://haarness.ai/docs/cli/configuration.md)
- [Data and storage](https://haarness.ai/docs/security/data-and-storage.md)