---
title: Troubleshooting
description: Known situations and what to do about them.
sidebar:
  order: 11
---

## Verbose logs

Set `ROLLE_DEBUG=1`, pass `rolle --debug`, or turn on **Settings → General → Verbose logging**. The desktop app and the CLI then log every provider call.

## `ExpiredToken` or the wrong identity after Start

If `~/.aws/credentials` holds static keys under the same profile name, the AWS credential chain reads those before rolle's `credential_process`. rolle refuses to start a session onto such a profile and names the file. Delete that section from `~/.aws/credentials`, or give the session another profile name.

## "login required" when a role starts

The Identity Center token for that portal is expired or revoked. **Start** in the desktop app and in the tray menu opens the sign-in first. On the command line, `rolle integration sync <alias>` signs in when it must, and `rolle integration login <alias>` always signs in. The integration's dot in the sidebar turns gray within thirty seconds of the token going bad.

## `gcloud` is not found

rolle looks for `gcloud` on your `PATH`, then in the usual install locations: Homebrew, the Google Cloud SDK installer, and [mise](https://mise.jdx.dev) installs. An app started from the Dock or the Start menu does not get your shell's `PATH`. rolle cannot find a `gcloud` that only your shell can see. Install the SDK with Homebrew, the official installer, or `mise use -g gcloud`. Run the sign-in command on the Google Cloud connect step. Then press **Check again**.

## TLS errors behind an inspecting proxy

rolle trusts the OS trust store. Install your organisation's root there (Keychain Access on macOS, `certmgr` on Windows, `update-ca-certificates` on Linux). If the root is only available as a file, set **Settings → Advanced → Extra CA bundle** to that PEM. Set **HTTPS proxy** when the app runs without your shell's proxy variables.

## macOS asks for keychain access

rolle stores refresh tokens and access keys in the login keychain under the service `rolle`. Choose **Always Allow** so every start does not prompt.

## The Dock or Finder says "Rolle"

The updater replaces the app inside the installed folder and keeps the folder's name, and macOS shows that name. The app works. To get the lowercase name, move the app to the Trash and install it again from the DMG or with `brew reinstall --cask rolle`.

## Windows SmartScreen warning

Windows builds are not code signed yet. Choose **More info → Run anyway**.

## Linux app does not start

The desktop app needs GTK 4 and WebKitGTK 6.0. On Debian and Ubuntu:

```sh
sudo apt-get install libgtk-4-1 libwebkitgtk-6.0-4
```

## Start over

```sh
rolle reset
```

This removes the workspace, every keychain entry, the credential cache, and the AWS profiles rolle wrote. The desktop app runs onboarding again.

## Get help

Open an issue at [github.com/nateships/rolle/issues](https://github.com/nateships/rolle/issues/new/choose). **Settings → About → Report a problem** and the tray menu open the bug form with your version and platform filled in.

Attach a support bundle: **Settings → About → Support bundle**, or `rolle support` on the command line. It writes a zip to Downloads with your settings, a redacted copy of the workspace, the AWS config, the az and gcloud profile files and tool locations, and the most recent diagnostic lines from every provider. Account ids, emails, GUIDs, portal hosts, and anything that looks like a secret are replaced with placeholders. Keychain entries and cached credentials are never included.