---
title: Troubleshooting
description: What a message or state in Polaris means, and what to do about it.
---

Each entry names what you see and what to do. The linked page has the details.
Labels in bold are what Polaris shows; agent names such as Codex or Claude Code
change with the Session.

## Signing in and opening Polaris

### "Polaris couldn't be reached"

Polaris couldn't load. Check your internet connection and reload the page.

### "Your session expired"

Sign in again. Your Sessions and their work are still there.

### "Polaris can't open here"

Polaris refused a request it needs to start, such as loading your account, so
reloading gives the same answer. Polaris can't show the support form here, so
email [andreas@plrs.sh](mailto:andreas@plrs.sh) with what you were doing.

### I signed in but can't see my team's work

You may not be a member of that organization yet. Ask one of its owners to
invite you; see [Organizations](/docs/organizations).

### A page shows an error

Select **Reload** to load the page again. A link to a page that doesn't exist
shows **Go to Polaris**, which opens **Start**.

## Starting a Session

### My repository isn't in the list

Select **Connect GitHub repository** and give the Polaris GitHub App access to
it. In a team, an owner or admin can add it in **Settings → GitHub**; see
[GitHub](/docs/github).

### "Polaris is still checking access to this repository."

Wait a moment, then start again.

### "Polaris lost access to this repository."

Owners and admins select **Open GitHub settings**, update access, then start
again. Members ask an organization admin.

### "This project or setup no longer exists."

Choose another Project.

### "This agent can't run on this machine."

Refresh the page and choose another agent.

### Models changed

The model or effort you chose is no longer offered. Review them and start
again.

### Machine setup failed

The new Machine didn't finish starting. Select **Try setup again**; nothing
ran, so nothing was lost.

### Couldn't reach GitHub

GitHub didn't respond while the Machine was getting your code. Select **Retry**
in the same Session.

### Branch not found

The branch no longer exists. Start again from **Start** with another branch.

### Couldn't access the repository

Polaris couldn't read the repository's code, usually because the Polaris GitHub
App lost access to it. Reconnect the repository in **Settings → GitHub**, then
try again.

### Couldn't start a Machine

Polaris can't start new Machines right now, and the Polaris team has been
alerted. Try again in a little while.

## Messages

### My message says Not sent or Not queued

Polaris couldn't save the message. Select **Retry**; it can't send the message
twice. If only **Remove** is offered, remove it and send it again.

### My message says Not confirmed

Polaris couldn't confirm that it saved the message. Select **Retry**. Polaris
uses the same message, so the agent can't get it twice.

### My message says Couldn't confirm the agent got this

Polaris stopped trying to deliver the message without knowing whether the agent
got it. Watch whether the agent answers it. To send it anyway, select **Send
again**; Polaris asks first, because the agent may repeat the work. **Edit**
puts the text in the composer so you can change it first.

### My message says Not delivered

The agent didn't get the message. If Polaris loses contact with a Machine and
puts it to sleep while your message is waiting to be delivered, it can wake the
Machine once automatically. If that wake fails or the Machine loses contact
again, select **Retry**. The message stays in the Session, with the action that
can help:

- **Retry** sends it once the Machine can take it.
- **Send again** sends it as a new message, and **Edit** puts it in the
  composer. **Attachment unavailable** on a message with an image offers both.
  When an attached file was the problem, such as one that says it's no longer
  available, only **Edit** is offered, so you can attach it again.
- **Contact support** appears when Polaris can't deliver it on its own. Your
  message stays saved.
- No action means the Machine is gone; see
  ["This machine is no longer available."](#this-machine-is-no-longer-available).

### "Your message is saved. Restart the agent to apply the selected configuration."

The settings you chose for this message need a fresh start of the agent. Select
**Apply changes…**, then **Restart and apply**. Restarting can interrupt other
Sessions and background work on the same Machine; the Session's history stays.
**Apply changes…** is also in the Session's **Session actions** menu.

### "Agent isn't starting · Polaris is retrying"

The agent keeps stopping as it starts. Polaris keeps trying by itself and sends
your message once the agent starts, so you don't need to do anything. To cancel
the message, select **Stop agent**.

If the agent still doesn't start after several tries, usually within about ten
minutes, Polaris stops trying and your message says **Not delivered**. Select
**Retry** to try again with a fresh start; your message is sent once. Sending a
new message also tries it again.

### "Couldn't reach the Machine to stop. Try again."

Select **Stop agent** again.

### An attachment says Upload failed

Select **Retry** on the attachment.

### The composer says Watch only

You can follow this Session but not send messages in it. Ask the Session's
owner for access; see [Share a Session](/docs/share-a-session).

### The Session says Reconnecting…

The live connection dropped. The transcript stays readable and your draft stays
in the composer. Polaris catches up on its own; you don't need to refresh.
After two continuous minutes with this page visible, **Could not reconnect**
appears with **Retry** alongside
your transcript. Select **Retry** to try again now; Polaris also continues
trying in the background. If no history has loaded yet, it shows **Session
history is unavailable** with **Retry** instead.

### The sidebar says Reconnecting…

The sidebar is waiting for current Session updates. Any rows already loaded stay
readable and their actions remain available. Polaris reconnects on its own;
the message clears when updates resume. You don't need to refresh.

## When the agent stops

### The Turn says The agent stopped unexpectedly.

The agent stopped before the Turn finished. What it already did stays. Send a
message to continue, or select **Report a problem** to send a report with this
Session attached.

### Your message wasn't saved

The agent stopped right after it took your message, before it saved it. When the
agent continues, it won't have that message. Select **Retry** to send it again.

### The agent couldn't finish this turn

The agent reported a failure, and its own explanation shows on the row. Select
**Continue** to carry on, or **Switch Codex account** (or the Session's agent)
to try another account. Continuing doesn't resend your message.

### Machine needs attention

The Machine stopped before the Turn could finish. Send your message again. If
it keeps happening, select **Contact support**.

### "Part of this session is missing from this view because of a Polaris error."

A Polaris error hides part of the history. It doesn't stop the agent, and
**Stop agent** still works. Select **Contact support**. The notice clears once
Polaris can read the history again.

## Agent accounts

### Usage limit reached

The agent's account hit its usage limit, for example **Claude Code usage limit
reached**. With **Switch accounts at usage limits** on, Polaris moves to another
connected account and continues for you. Otherwise, select **Switch Claude Code
account** to pick another account, or wait for the limit to reset and select
**Continue task**. See [Agent accounts](/docs/agent-accounts).

### Agent credentials need attention

The agent couldn't sign in with its account, so the Turn didn't run. Select
**Reconnect** with the agent's name, then sign in again or paste a new key.

### My message waits for an agent account

The row under your message says why, such as **No Codex account is connected.**
or **Codex needs you to sign in again.**, with one action, such as **Connect
Codex**. Polaris sends every waiting message as soon as an account works, so
you don't send them again. **This organization uses its own Codex accounts.**
means an Owner or Admin turned off members' own accounts: choose one of the
organization's accounts. See [Agent accounts](/docs/agent-accounts).

## The Machine

### The transcript ends with Machine went to sleep

Machines sleep when nothing needs them. Send a message to wake it. Your files
are kept, but programs such as a dev server stop until they're started again;
see [Previews](/docs/previews).

### A panel says Machine is asleep

Select **Wake machine**, or send a message.

### "Polaris can't send work to this machine. Go to Start to continue."

Polaris can't reach this Machine. Open **Start** and start a new Session from
the same repository. Work the agent pushed is safe on GitHub.

### "This machine is no longer available."

The Machine is gone, so this Session can't continue. Its transcript stays
readable. Start a new Session from the same repository, or select **Contact
support** if you didn't expect it. **Machine unavailable** on a Turn means the
same. See [Machines](/docs/machines).

## Setup, variables and Previews

### A setup row says .agents/setup failed

The script failed, but the Session still works. Select **View log** to see why,
then **Ask agent to fix**. A row that says **Not executable** needs the same
fix. See [Workspace setup](/docs/workspace-setup).

### A resume row says Project variables unavailable

Polaris couldn't load the Project's variables, so `.agents/resume` didn't run.
Check the Project's [environment variables](/docs/environment-variables), then ask
the agent to run resume again.

### The first Turn says Waiting for setup

The Project waits for setup before the agent starts. Select **Start now** to
start it anyway.

### A command doesn't get a variable

Commands get the Project's variables only when started through Polaris. Ask the
agent to run it with the Project's variables, or see
[Machine commands](/docs/machine-commands#environment-variables) to do it in the
Terminal.

### A Preview doesn't load

- **Machine is asleep**: select **Wake machine**.
- **Website is unavailable**: the Machine is awake but your app isn't running.
  Ask the agent to start it again.
- **Preview is unavailable**: try again, or open the Session to check the app.
- **Machine is unavailable**: open the Session to check the Machine.
- **Preview is no longer available**: ask the agent for a new Preview.

### Browser didn't start or Desktop didn't start

Select **Try again**. See [Browser and Desktop](/docs/browser-and-desktop).

## GitHub

### GitHub access needs attention

The Session owner's GitHub sign-in expired. They select **Reconnect GitHub**.
The agent keeps working on the Machine meanwhile.

### GitHub access is temporarily unavailable

Wait a moment and try again. You don't need to sign in again.

## Cloud access

Agents see these messages when they use [Cloud access](/docs/cloud-access), and
usually tell you what they mean. Each starts with `polaris:`.

| Message | What to do |
| --- | --- |
| `cloud credentials are unavailable right now. Try again shortly.` | Try again in a minute. |
| `isn't available to this Project.` | Ask an organization admin to add this Machine's Project to the role. |
| `needs approval. Ask with: polaris access request …` | Ask the agent to request access, then approve it in the Session. |
| `this role is always available.` | The role needs no request. Use its profile directly. |
| `this Machine can't get cloud credentials right now.` | Try again shortly. If it keeps happening, contact support. |
| `this role's AWS trust configuration refused access.`, `AWS rejected this role's identity token.`, `this role's AWS configuration is invalid.`, or AWS refuses `sts:AssumeRoleWithWebIdentity` | Ask an organization admin to test the connection in **Settings → Cloud access** and fix the failed check. |
| `this audience isn't allowed.` | Compare the audience with the service's **Token audience** in **Settings → Cloud access**, or ask an admin to connect the service. |

[Machine commands](/docs/machine-commands#cloud-access) has the commands behind
these messages.

## Still stuck?

Select **Contact support** where Polaris offers it, or ask the agent to report
the problem. [Report a problem](/docs/feedback) shows every way to reach the Polaris
team.