# Troubleshooting

[Documentation index](README.md) · [Getting started](getting-started.md) · [Interaction guide](interaction-and-accessibility.md)

## “requires Pi TUI mode”

Rich forms are custom terminal components. Start Pi interactively; RPC, JSON, and print modes cannot display them. If an integration needs non-interactive input, use ordinary text or another interface instead of this package.

After installation or changes, restart Pi or run `/reload`. Confirm the package is installed and enabled with `pi list` and `pi config`.

## `/rich-questions` finds no assistant message

The command only inspects the latest completed assistant message containing text. In an empty session it offers a demo. If the latest response is still streaming, wait for it to complete. To test from a fresh session, enter `demo pi-rich-questions` as a normal request.

## No authenticated extraction model

Session-model mode requires the current session model to be authenticated. Dedicated mode only lists models Pi reports as available. Authenticate/configure a provider through Pi, confirm a model is selected, then run `/rich-questions config` again.

If a configured dedicated model has disappeared or lost authentication, extraction tries the current session model. `/rich-questions reset` returns directly to session-model/low-thinking mode. With no usable model, the broad fallback still preserves the original assistant text in one freeform question.

## Extraction returned malformed data

The extractor accepts plain JSON or JSON in a fenced block, then validates it against the public schema. Invalid JSON, wrong question types, missing prompts, or malformed options cause the current attempt to fail. A dedicated attempt retries with the session model; final failure activates the broad fallback.

If this repeats:

1. choose a different authenticated model with `/rich-questions config`;
2. retry on a shorter assistant response to distinguish context/provider problems;
3. record the provider/model and visible notification, but do **not** post private prompt contents or credentials;
4. file an issue with a redacted reproduction.

The fallback is expected recovery behavior, not silent data loss: it includes the complete original assistant message.

## Keys behave differently in my terminal

Pi Editor and Pi's injected selection bindings interpret keys. Modified Enter sequences and Page Up/Page Down can vary across terminals, multiplexers, and keybinding configuration.

- Press `Ctrl+H` to view the in-form guide.
- Try the newline sequence documented for your Pi/terminal setup if `Shift+Enter` is not distinct.
- Check whether tmux, screen, a terminal shortcut, or custom Pi keybindings intercept the key.
- Include terminal, OS, multiplexer, Pi version, and key-protocol settings in a report.

See [Interaction and accessibility](interaction-and-accessibility.md#multiline-input-and-terminal-protocols).

## Rendering, width, scrolling, or cursor problems

First enlarge the terminal and run `/reload`. The extension uses ANSI/Unicode-aware Pi TUI helpers and a height-limited modal, but behavior also depends on terminal width reporting and Pi Editor.

For reproducible problems, note terminal columns/rows and whether the content contains ANSI styling, CJK, emoji, combining characters, very long tokens, or IME input. State whether the cursor marker disappears, the form exceeds terminal height, or Page Up/Page Down scrolls the transcript instead of the modal. A minimal redacted form is more useful than a screenshot alone.

## Required answers will not submit

Required questions default to `required: true`. A required text answer must contain non-whitespace text; a required radio needs one selection; a required checkbox needs a predefined or custom selection. Navigate back with `Shift+Tab` or `←`, answer the highlighted missing item, and return to review.

## Conflicts with other question extensions

Extensions that register overlapping Q&A tools can make tool selection confusing even if they use different names. Use `pi config` to disable competing packages such as `pi-answer` or `pi-mono-ask-user-question`, then `/reload`. Avoid loading both an installed package and a separate development copy of Pi Rich Questions.

## Settings do not persist

Extraction settings are written under Pi's global agent directory. Check that the directory selected by `PI_CODING_AGENT_DIR` (or the default `~/.pi/agent`) is writable. Invalid or unsupported settings are ignored and the first-run chooser returns. Do not hand-edit credentials into `pi-rich-questions.json`; provider authentication belongs to Pi.