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

# TUI Troubleshooting

> Fix common Papermap TUI installation, login, workspace, streaming, shell mode, and configuration issues.

Use this guide when the `papermap` command starts but login, workspace loading, streaming, or shell mode does not behave as expected.

## Quick checks

Run these first:

```bash theme={null}
papermap --version
papermap auth whoami
papermap workspace list
```

If `whoami` says you are not signed in, run:

```bash theme={null}
papermap auth login
```

## Common issues

<AccordionGroup>
  <Accordion title="Browser did not open during login" icon="browser">
    The CLI prints the login URL after attempting to open your browser. Copy the printed URL into your browser manually.

    ```bash theme={null}
    papermap auth login
    ```

    If you are on SSH or a headless machine, use the password fallback instead.

    ```bash theme={null}
    papermap auth login --password
    ```
  </Accordion>

  <Accordion title="Login timed out" icon="clock">
    Browser login waits for a localhost callback for a limited time. Restart login and complete the browser flow promptly.

    ```bash theme={null}
    papermap auth login
    ```

    Also check that your browser can reach the printed `http://127.0.0.1:<port>/callback` URL after Papermap redirects.
  </Accordion>

  <Accordion title="Custom frontend URL is rejected" icon="shield-halved">
    Browser login only allows production Papermap frontend hosts by default. Internal or development frontends require an explicit opt-in.

    ```bash theme={null}
    PAPERMAP_ALLOW_UNTRUSTED_FRONTEND=1 \
      papermap auth login --frontend-url https://internal-frontend.example
    ```

    Only use this with frontends you control.
  </Accordion>

  <Accordion title="Session expired" icon="key">
    The TUI attempts token refresh before forcing a new sign-in. If refresh fails, sign in again.

    ```bash theme={null}
    papermap auth login
    papermap
    ```

    If the issue repeats, log out and start with clean local auth state.

    ```bash theme={null}
    papermap auth logout
    papermap auth login
    ```
  </Accordion>

  <Accordion title="No workspaces appear" icon="database">
    Confirm your account has access to workspaces.

    ```bash theme={null}
    papermap workspace list
    ```

    If the CLI returns no rows, create a database-backed workspace or use the web app to configure sources that require browser-based setup.

    ```bash theme={null}
    papermap workspace create
    ```
  </Accordion>

  <Accordion title="Workspace picker looks stale" icon="rotate">
    Refresh the local workspace cache, then relaunch the TUI.

    ```bash theme={null}
    papermap workspace list
    papermap
    ```

    Logout also clears the workspace cache.

    ```bash theme={null}
    papermap auth logout
    ```
  </Accordion>

  <Accordion title="Workspace creation returns before connection is verified" icon="circle-info">
    This is expected. `papermap workspace create` creates the workspace row first, then Papermap verifies the database connection in the background.

    If the workspace later cannot answer questions, verify the host, port, database name, username, password, network access, and database permissions.
  </Accordion>

  <Accordion title="Shell mode did not start" icon="terminal">
    `!` starts shell mode only from an empty prompt. If your prompt already has text, `!` is typed into the prompt instead.

    Clear the prompt with `Ctrl+L`, then press `!` again.
  </Accordion>

  <Accordion title="Shell command is stuck or running too long" icon="ban">
    Press `Esc` to cancel the running shell command. Shell mode uses one-shot commands; there is no persistent shell session inside the TUI.
  </Accordion>

  <Accordion title="Windows says pwsh.exe was not found" icon="window">
    The default Windows shell is PowerShell 7 (`pwsh`). Install PowerShell 7 or switch shell mode to Command Prompt.

    ```yaml theme={null}
    shell:
      windows: cmd
    ```

    Save the file at `C:\Users\<name>\.papermap\config.yaml`, then restart `papermap`.
  </Accordion>

  <Accordion title="Credential store fails in CI or a container" icon="lock">
    Force file-backed credential storage when the OS keyring is unavailable.

    ```bash theme={null}
    PAPERMAP_FORCE_FILE_STORE=1 papermap auth login
    ```

    Keep `~/.papermap/credentials` private and out of source control.
  </Accordion>

  <Accordion title="The terminal is too small" icon="maximize">
    Papermap needs enough room to render the landing panel, chat layout, overlays, and key hints. Resize the terminal to at least roughly `60x20`, then relaunch or continue.
  </Accordion>

  <Accordion title="Slash does not open the command palette" icon="slash">
    `/` opens the command palette only when the prompt is empty and the TUI is not streaming. Clear the prompt with `Ctrl+L`, then press `/`.
  </Accordion>

  <Accordion title="Thinking traces are hidden" icon="brain">
    Press `Ctrl+T` to toggle thinking traces. To show them by default, set this in `~/.papermap/config.yaml`.

    ```yaml theme={null}
    show_thinking: true
    ```
  </Accordion>
</AccordionGroup>

## Reset local state

Use logout when you want to clear credentials and workspace cache.

```bash theme={null}
papermap auth logout
papermap auth login
papermap
```

Local paths to inspect when debugging:

| Path                          | Purpose                   |
| ----------------------------- | ------------------------- |
| `~/.papermap/config.yaml`     | TUI settings              |
| `~/.papermap/credentials`     | File fallback credentials |
| `~/.papermap/workspaces.json` | Workspace cache           |

<Warning>
  Do not paste credential file contents into support tickets or commits. Share error messages and command output only after removing secrets.
</Warning>

## Still need help?

<CardGroup cols={2}>
  <Card title="Contact Support" icon="envelope" href="mailto:team@papermap.ai">
    Send the command you ran, the error output, your operating system, and whether you used browser or password login.
  </Card>

  <Card title="Book a Demo" icon="calendar" href="https://calendly.com/admin-pappermap/30min">
    Get guided help setting up Papermap for your team.
  </Card>
</CardGroup>