# Troubleshooting

Start with `/advisor`. It shows the effective model, Advisor State, settings sources, tool state, and file errors.
In the TUI it also opens the model picker. Dismiss the picker if you only need the status.

Settings refresh before each Prompt Cycle and after setters. Tool selection stays fixed within a Prompt Cycle.
Notices appear through pi notifications in the TUI and on stderr without a UI.
RPC mode also writes notices to stderr because yaag does not display notification frames.
A notice appears once while its condition persists. It can appear again after a refresh without that condition.
The invalid-pair and conflicting-tool notices each appear only once per session.

Text in angle brackets, such as `<path>` or `<cause>`, is a placeholder for a value from your session.
Numeric examples use three Consultations, three failed calls, a 120-second timeout, and file version 2.
Each blockquote has a source marker for the exact-text guard.

See [Consultations](consultations.md) for limits, mechanisms, redaction, display, and cost.

## Consultation failures

### Consultation limit

<!-- quote: src/consultation/consultation-texts.ts -->
> Advisor limit: you used 3 of 3 Consultations for this user message. Continue without the Advisor.

**Cause:** The Prompt Cycle used all three Consultations in this example.

**Action:** Continue without advice. A new user message starts a new Prompt Cycle and resets the limit. This skipped call does not count.

### Duplicate call

<!-- quote: src/consultation/consultation-texts.ts -->
> One Consultation for each turn. Read the result of the first advisor call.

**Cause:** The Executor called advisor more than once in one assistant message.

**Action:** Use the first result. A later assistant message can make another Consultation if the limit permits it. The duplicate does not count.

### Unavailable model

<!-- quote: src/consultation/consultation-texts.ts -->
> The Advisor is not available: <provider>/<id> is not in the model registry. Continue without the Advisor.

**Cause:** The configured model identifier does not exist in pi's model registry.

**Action:** Correct the provider/model identifier. Continue without advice now. Settings refresh at the next Prompt Cycle. This failure does not count.

### Missing authentication

<!-- quote: src/consultation/consultation-texts.ts -->
> The Advisor is not available: <provider>/<id> has no auth. Continue without the Advisor.

**Cause:** The model exists, but pi has no authentication for it.

**Action:** Configure credentials for that provider through pi. Do not change a valid model identifier to fix credentials. Continue without advice now. This failure does not count.

### Unset model

<!-- quote: src/consultation/consultation-texts.ts -->
> The Advisor is not available: the Advisor model is not set. Continue without the Advisor.

**Cause:** The Advisor model is off or absent. This is a defensive result because the normal off state removes the tool.

**Action:** Set a model with /advisor model <provider/id>. Continue without advice now. The next Prompt Cycle can use the model. This failure does not count.

### Invalid settings

<!-- quote: src/consultation/consultation-texts.ts -->
> The Advisor is not available: the advisor settings are not valid. Continue without the Advisor.

**Cause:** Settings are invalid. This defensive result can occur if the tool is still called while the Advisor is off.

**Action:** Inspect /advisor. Correct the invalid file or override. Continue without advice now. This failure does not count.

### Model request error

<!-- quote: src/consultation/consultation-texts.ts -->
> The Advisor request failed: <cause>. Continue without the Advisor.

**Cause:** The provider request failed. The cause contains the provider's error or stop reason.

**Action:** Continue without advice. Correct the reported cause before a later retry. Fix authentication for credential errors, not the model identifier. A sent request counts toward the limit.

### Timeout

<!-- quote: src/consultation/consultation-texts.ts -->
> The Advisor did not reply in 120 seconds. Continue without the Advisor.

**Cause:** The request did not finish within timeoutMs. This example uses the default 120 seconds.

**Action:** Continue without advice. Check provider availability. Increase timeoutMs only if the request needs more time. A sent request counts. Retry in a later Prompt Cycle if needed.

### Invalid redaction pattern

<!-- quote: src/consultation/consultation-texts.ts -->
> The redact pattern <pattern> is not a valid regular expression: <cause>. Continue without the Advisor.

**Cause:** A custom redact pattern does not compile as a regular expression.

**Action:** Correct the pattern in the global or trusted project settings file. Both files contribute patterns. Continue without advice until settings refresh. This failure does not count.

### Empty advice

<!-- quote: src/consultation/consultation-texts.ts -->
> The Advisor gave empty advice 2 times. Continue without the Advisor.

**Cause:** The Advisor returned empty advice twice. The package already retried once within the same Consultation.

**Action:** Continue without advice. Check the model or provider before retrying in a later Prompt Cycle. The two attempts count as one Consultation and their usage combines.

## Abort

An abort currently uses the request-failure result above, with the actual abort cause.
There is no separate fixed package message for an abort.
An abort before the request does not count. An abort after sending the request counts.
Pi can replace the displayed tool result with its own abort handling.
Resume only when you want the Executor to continue. Use a later Prompt Cycle if you need a fresh Consultation limit.

## Settings notices

### Invalid settings file

<!-- quote: src/settings/settings-notices.ts -->
> Advisor off: <path> is not valid: <error>.

**Cause:** The named file failed JSON or schema validation. Settings errors disable the Advisor.

**Action:** Correct the named file. A higher-precedence model override cannot repair an invalid file. Settings refresh before the next Prompt Cycle or after a setter.

### Unknown version

<!-- quote: src/settings/settings-notices.ts -->
> Advisor off: <path> has version 2. This @yaag/advisor reads version 1. Update @yaag/advisor.

**Cause:** The file has version 2 in this example. This package reads version 1.

**Action:** Update @yaag/advisor to a compatible version, or restore a valid version-1 file. Do not merely change the version number of an incompatible file.

### Invalid flag or environment value

<!-- quote: src/settings/settings-notices.ts -->
> Advisor off: <source> has a value that is not valid: <error>.

**Cause:** A CLI flag or environment variable has an invalid value.

**Action:** Correct or remove the named override. Editing a lower-precedence file does not remove it. Environment changes require a process that inherits the corrected environment. CLI changes require a new session.

### Unknown key

<!-- quote: src/settings/settings-notices.ts -->
> Advisor settings: <path> has an unknown key <key>. The advisor ignores it.

**Cause:** The named key is not in the settings schema. The package ignores it without disabling advice.

**Action:** Correct a spelling error or remove the unused key. Check /advisor after the next refresh.

### Unresolved model identifier

<!-- quote: src/settings/settings-notices.ts -->
> Advisor off: <provider>/<id> is not in the model registry.

**Cause:** The effective model does not exist in the registry.

**Action:** Correct the identifier at its reported source. Remove a higher-precedence override if it hides the intended file value. The Advisor remains off until a successful refresh.

### Unresolved model authentication

<!-- quote: src/settings/settings-notices.ts -->
> Advisor off: <provider>/<id> has no auth.

**Cause:** The effective model has no authentication.

**Action:** Configure credentials in pi for that provider. Keep a valid model identifier. The Advisor remains off until resolution succeeds at a refresh.

## Native notices

### Executor model switch

<!-- quote: src/settings/settings-notices.ts -->
> Native advisor off: <provider>/<id> is not a yaag-advisor model. The client-side advisor is on.

**Cause:** The Executor switched away from the yaag-advisor provider.

**Action:** Use Client-side Consultations. Switch back to a yaag-advisor Executor for Native Consultations at the next Prompt Cycle. This temporary switch does not disable native support for the session.

### Invalid native pair

<!-- quote: src/native/native-texts.ts -->
> Native advisor off for this session: the API refused the advisor tool: <API error>. The client-side advisor starts at the next user message.

**Cause:** The API refused the native Executor/Advisor pair. The embedded reason includes the API error.

**Action:** Continue without native advice. Client-side Consultations start at the next Prompt Cycle. Native support stays off for this session, even after a model switch. Correct the pair before starting a new session.

### Conflicting advisor tool

<!-- quote: src/native/native-texts.ts -->
> Native advisor: a pi tool with the name advisor is active. The provider does not send the native advisor tool.

**Cause:** Another active pi tool has the name advisor. The provider omits the native server tool to prevent a name collision.

**Action:** Remove or rename the conflicting pi tool to restore the native tool. Do not disable the Advisor entirely unless you want no advice. The next request checks active tool names again.

### Automatic native replay recovery

If the API cannot process a replayed Advisor result, the package automatically retries without the old native Advisor blocks.
This replay recovery retains the current native tool plan. It does not disable Native Consultations.
This recovery emits no package notice. It is different from invalid-pair recovery, which disables native support for the session.

## Command failures

### Model command: unknown identifier

<!-- quote: src/command/command-texts.ts -->
> /advisor model: <provider>/<id> is not in the model registry.

**Cause:** The requested model is not in the registry. The command writes no file.

**Action:** Use a registered provider/model identifier. Retry the command after correction. A command failure consumes no Consultation.

### Model command: authentication

<!-- quote: src/command/command-texts.ts -->
> /advisor model: <provider>/<id> has no auth.

**Cause:** The model exists but has no authentication. The command writes no file.

**Action:** Configure provider credentials through pi. Retry the same valid identifier after authentication succeeds.

### Untrusted project

<!-- quote: src/command/command-texts.ts -->
> /advisor --project: this project is not trusted. Trust the project, or write the global file without --project.

**Cause:** The --project setter requires project trust.

**Action:** Trust the project through pi, or omit --project to write the global file. Spawned Agents use saved trust decisions. Retry after correcting trust or the command.

### Command refuses invalid file

<!-- quote: src/command/command-texts.ts -->
> /advisor: <path> is not valid: <error>. Correct the file before you change it with /advisor.

**Cause:** The existing target file fails validation. Setters do not overwrite an invalid file.

**Action:** Correct the named file manually before retrying /advisor. For an unknown version, install a compatible package or restore a compatible file.

### Write failure

<!-- quote: src/command/command-texts.ts -->
> /advisor: cannot write <path>: <cause>.

**Cause:** The package could not write or replace the target file.

**Action:** Check the reported cause, directory permissions, and available storage. Correct the filesystem problem, then retry the command. Inspect /advisor to check the effective value and any higher-precedence override.

A successful setter can still be hidden by a higher-precedence override.
See [precedence](configuration.md#precedence) before changing another file.
Return to the [README](../README.md).