Reference

Troubleshooting

Most problems show up in one of two places: the Credentials page, which shows the last error verbatim, or the Activity page, which shows the step it happened in.

Where to look first

1. Credentials — the token's state and the last error, verbatim from AWS.
2. Activity — which of the three steps failed, and what it had found before it did. Activity & logs →
3. The log file for that day, which follows the run poll by poll. Paths are in files & locations.

Sign-in fails or never completes

"Login window closed"

The login window was closed before AWS confirmed the approval. Frost treats that as "not now" and aborts the run. It does not start another one on its own — trigger a refresh from the tray or the Credentials page when you are ready.

"Login timed out"

The device code AWS issued expired before the sign-in was approved. Frost stops there and the tray menu shows Sign-in needed; start another refresh when you are back. If this happens repeatedly in notify mode, you may simply not be getting the notification — see below.

A pile of login tabs or windows waiting for me

Fixed in the version after 0.1.0. A failed sign-in used to be retried twice a second from the moment the token expired, and in Default browser mode each attempt opened a tab, so a machine left alone overnight collected one every few minutes. Frost now waits for you after a sign-in nobody completed, and only retries by itself for failures that never put anything on your screen.

An AWS error naming the client or the endpoint

Almost always a region mismatch: a client registered in one region means nothing in another. Check the AWS Region on the Login page against the region your IAM Identity Center instance actually lives in, and save again — saving re-registers everything. Login settings →

The login page is stuck, or signs you in as the wrong person

The in-app login window keeps its cookies between sign-ins, so a stale identity provider session or a half-finished redirect can persist. Press Clear Cookies on the Behavior page and start another refresh — your settings and profiles are kept. Behavior settings →

Frost asks for a fresh sign-in after you copied its configuration

Expected. The stored token and client secret are encrypted with the operating system's credential store, so a configuration file copied from another machine — or restored after a keychain reset — cannot be decrypted. Frost treats that as having no credential and signs you in again rather than failing later with an AWS error. Security & privacy →

The sign-in page loads but your key or passkey does nothing

Frost's own login window supports hardware security keys but cannot reach passkeys or password managers stored in your browser. Switch Login Page to Default browser on the Behavior page. Behavior settings →

Credentials expire while I work

• Check Frost is actually running — the tray icon should be there, and the menu should show when the next refresh is due.
• If you are in notification + hotkey mode, nothing refreshes until you act. Either respond to the notification, or switch to Auto-open browser. Behavior settings →
• Check the last run on the Activity page — a failing token step leaves the old token in place until the next attempt succeeds.
• Confirm your tool is reading the profile Frost wrote (--profile or AWS_PROFILE) rather than static credentials in ~/.aws/credentials, which take precedence in the AWS credential chain.

Notifications never arrive

• Press Test on the Behavior page. On macOS, the first notification triggers the permission prompt — allow it. If you dismissed it earlier, enable Frost under System Settings → Notifications.
• On Windows, check Focus assist / Do not disturb, and that Frost is allowed to send notifications.
• On Linux, notification support depends on your desktop's notification daemon.

The hotkey does nothing

• Another application may already hold that combination; a hotkey that cannot be registered silently does nothing. Try a different one on the Behavior page.
• The hotkey does nothing while a refresh is already running — that is deliberate.
• On macOS, some combinations are reserved by the system and cannot be claimed by an app.

A profile is missing or looks wrong

It never appeared

Open the last run on the Activity page and look at the profiles step: it lists every account and permission set the token could reach. If the account is not there, the access is not there — that is an Identity Center assignment question, not a Frost one.

It is in the list but not in ~/.aws/config

Frost never overwrites a profile it does not own. If a profile of the same name already exists without the # frost:managed marker, yours wins and Frost skips its own. Rename or remove yours, or check whether two AWS accounts produce the same generated name. The config file →

It disappeared

Marked profiles are removed when the corresponding account or permission set is no longer returned by Identity Center. To keep one anyway, delete its marker line — Frost then leaves it alone permanently.

The name is too long, or in the wrong region

Both are controlled by the AWS account name: #short-name shortens the account part and @region pins the profile region. Profile names →

kubectl cannot reach a cluster

"executable … not found" or a path error

The kubeconfig entry points at the authenticator inside the Frost application. If Frost moved — or, on Windows, was updated into a new versioned directory — run a refresh; entries are rewritten with the current path. Authenticator →

"You must be logged in to the server (Unauthorized)"

The token was produced but the cluster does not recognise the IAM principal. That mapping lives in the cluster (EKS access entries or the aws-auth ConfigMap) and has to be granted there. Check you are using the context for the permission set that was actually granted access — the context name usually carries it.

"ExpiredToken" from the authenticator

The underlying SSO session has expired and has not been refreshed. Run a refresh from the tray; kubectl picks the new token up on its next call.

No EKS clusters were found

• Open the EKS step of the last run: it lists what was found per region and how many regions returned access errors. Errors everywhere usually means the profiles genuinely have no EKS permissions.
• The region list comes from ec2:DescribeRegions with the first generated profile. If that call fails, the scan has nothing to iterate over.
• Clusters are only added when eks:DescribeCluster succeeds — listing alone is not enough.
• Clusters that disappear from AWS are not removed from your kubeconfig; delete stale contexts with kubectl config delete-context.

Linux-specific

• "OS keyring unavailable" in the log. Frost encrypts the stored token and client secret through libsecret or kwallet. On a headless or keyring-less machine there is nowhere to keep the key, so it stores them as earlier versions did and warns once. Installing a keyring your desktop session unlocks — gnome-keyring, kwallet — restores encryption at the next write. Security & privacy →
• No tray icon. Some desktops need an AppIndicator extension before Electron's tray appears. Platforms →

Windows-specific

• SmartScreen warns on the installer. Expected — the builds are unsigned. Choose More info → Run anyway. Platforms →
• A refresh fails writing ~/.aws/config. Windows refuses to replace the file while another process holds it open. The write retries briefly on its own; if it still fails, close whatever is holding the file (an AWS CLI command, an editor, an antivirus scan) and refresh again.
• Two tray icons. Should not happen — Frost only allows one instance. If it does, quit both and relaunch once.

Starting over

If Frost is in a state you cannot explain: quit it, delete its configuration file (paths here) and start it again. That clears the token, the OAuth client registration, the discovered inventory and the run history, and leaves your ~/.aws/config and ~/.kube/config as they are. You will need to enter your start URL and region again.

Still stuck

Open an issue with the failing step from the Activity page, the error text, the relevant log lines and the version from the log banner. Account names and ids do appear in logs — review what you paste.