---
title: "Troubleshoot Panolayer: setup, agents, and verification"
description: "Resolve Panolayer setup, sign-in, agent, verification, graph, and Git problems. Find your symptom, follow the recovery steps, and get help."
url: https://panolayer.com/docs/troubleshooting
type: HOW-TO
updated: 2026-10-21
---

# Troubleshoot Panolayer: setup, agents, and verification

Resolve Panolayer setup, sign-in, agent, verification, graph, and Git problems. Find your symptom, follow the recovery steps, and get help.

Last updated 2026-10-21

<a id="find-your-problem"></a>

## Find your problem

Start with the message you see in Panolayer. Use the table to jump to the relevant fix, then check the result before trying the next step.

| What’s going wrong? | Start here |
| --- | --- |
| Installation or the system check won’t finish | [Install and system check](#install-and-system-check) |
| The browser signs in, but the app is still waiting | [Finish sign-in](#section-4) |
| Your repository won’t open or looks incomplete | [Open the right repository](#open-your-repository) |
| An agent is missing, won’t launch, or reports an engine error | [Start an agent](#section-1) |
| An agent can’t read or modify a file | [Check file access](#agent-file-access) |
| Verification is interrupted, unavailable, or undecided | [Recover verification](#section-2) |
| A rule describes the wrong behavior | [Inspect the rule and its evidence](#section-3) |
| An agent stops, or you can’t find its changes | [Inspect the agent’s work](#inspect-the-agent-run) |
| A graph fails or returns an incomplete answer | [Check the graph step](#graph-step-fails) |
| A merge conflicts, or a push fails | [Resolve merge and push problems](#merge-and-push) |
| You still need help | [Report a reproducible bug](#section-5) |

**Keep the error and the work.** Note the exact message and where it appeared. Inspect the existing run or worktree before starting another task. You don’t need to delete your repository, agent worktree, or settings to follow this guide.

<a id="setup-help"></a>

## Setup help

**Still waiting for browser sign-in?**

Choose **Open the browser again** in Panolayer and finish approving the sign-in. If the request expired, choose **Try again** to start a new one.

**The browser is using the wrong account?**

Choose **Switch account** on the browser’s approval page, then sign in with the account you want.

**The system installer is no longer open?**

Choose **Re-open installer** on Panolayer’s system-check screen, then finish installing Apple Command Line Tools. Panolayer checks automatically while the installer runs.

For installation, verification, or agent problems, see [Troubleshooting](/docs/troubleshooting).

<a id="install-and-system-check"></a>

## Installation or the system check won’t finish

**Check your Mac first.** The Panolayer desktop app requires an **Apple silicon Mac** running **macOS 15 Sequoia or later**. Check **Apple menu → About This Mac** for your chip and macOS version. Intel Macs are not supported.

**If you downloaded Panolayer but it isn’t installed:** open the `.dmg`, drag **Panolayer** into **Applications**, then open it from Applications. Follow [Install and set up Panolayer](/docs/getting-started#install-panolayer) for the complete sequence.

**If you’re stuck on One quick system check:**

- Choose **Install** next to **Git — Apple Command Line Tools** and finish Apple’s installer.
- If you closed the installer, choose **Re-open installer** in Panolayer.
- Return to Panolayer after installation. It detects the tools automatically; choose **Choose a project** when the check is ready.

You’re ready to continue when Panolayer lets you choose a project. If Apple’s installer reports an error, include that exact error when asking for help.

<a id="section-4"></a>

## Sign-in does not finish

Signing in has two parts: authenticate in your browser, then approve that Mac for the Panolayer app. A signed-in website alone does not complete the app’s approval.

| What you see | What to do |
| --- | --- |
| The app is waiting and no browser page is open | Choose **Open the browser again** in Panolayer. |
| The browser shows a different account | Choose **Switch account**, then sign in with the account you want to use in the app. |
| The browser asks you to approve this computer | Compare its code with **Your code** in the app. When they match, choose **Yes, sign in on this computer**. |
| The request expired | Choose **Try again** in Panolayer and complete the new browser request. |
| The browser confirms approval | Return to Panolayer to continue setup. |

Use the same account in the app and on the website. See [Sign in](/docs/getting-started#sign-in) for the full walkthrough.

**A third-party agent asks you to sign in separately?** That is the agent vendor’s sign-in. Your Panolayer account does not replace it. Follow that agent’s instructions and [Supported agents](/docs/agents).

<a id="open-your-repository"></a>

## Your repository won’t open or looks incomplete

**Your project won’t open?**

Check that you selected the root folder of a local Git repository. If your repository is hosted online, clone it to your Mac first, then open that folder in Panolayer.

Choose **Open Project…** on Panolayer’s opening screen, then select the **root folder of your local Git repository**. A GitHub URL is not a local folder; clone the repository to your Mac first using your usual Git tools.

If the map looks incomplete:

- Check that you opened the intended repository root, rather than an individual file or the wrong subfolder.
- Check whether Panolayer is still analyzing the code or reports an indexing error. See [Recover verification](#section-2).
- Check [Supported languages](/docs/languages) for your codebase. Inspect the apps and relationships shown in **Architecture**, especially in a monorepo.

A detected framework or a visible file does not mean every dynamic relationship can be resolved. See [Explore architecture and dependencies](/docs/architecture).

**Use the sample to compare the workflow.** The docs use **Twitter Clone**, which opens as `twitter-starter`. Your own repository will have different files, issue counts, and dependencies. You do not need to switch to the sample to use Panolayer.

<a id="section-1"></a>

## An agent does not start

**Panolayer Agent is built in.** Open **My Agents**, choose the **+** button next to **Monitor Agents**, then select **Panolayer Agent**. It does not need a separate vendor sign-in. See [Run an agent on your repository](/docs/running-agents#start-agent).

**For another agent:** install it from **Marketplace**, return to **My Agents**, and choose it from the same menu. Complete the vendor’s sign-in when asked. Its model access and billing belong to that vendor; check [Supported agents](/docs/agents) for the relevant setup.

**If you see an agent failure card:**

- Open **Technical details** and read the launch error.
- If the **container engine could not start**, check the Mac requirements above, then use **Retry** on the failure card.
- If the message names missing credentials or an account problem, finish that agent’s sign-in before retrying.
- If it fails again with the same message, choose **Report a bug** on the failure card. That route includes the agent’s diagnostics. Review the report before sending it.

A successful launch opens the agent conversation so you can send a request. Repeatedly starting new sessions does not resolve an unchanged installation or account error.

### A request is rejected or your usage is exhausted

If Panolayer reports **You’re out of usage for this month**, open **Settings → Plan & Usage** to check the account’s usage and reset date. Retrying the same request does not restore exhausted usage.

For a third-party agent, check the vendor account named in its error. Signing in to Panolayer does not change that vendor’s quota or billing. Resolve the reported account issue before retrying.

<a id="agent-file-access"></a>

## An agent can’t read or modify a file

Check the file’s controls in **Architecture**. Open the file’s source and scroll down in its details panel.

| Control | What it changes |
| --- | --- |
| **Lock File**, under **Implementation Lock** | Prevents AI agents from modifying the file. |
| **Hide from Agents**, under **Container Agent Access** | Prevents new container agents from reading the file. Existing agent sessions are unchanged. |

![SavedPosts.tsx file controls in Architecture, showing Lock File under Implementation Lock and Hide from Agents under Container Agent Access.](/docs/getting-started/05-file-agent-access.png "Check these file controls when an agent cannot read or change a file. The screenshot uses SavedPosts.tsx in the Twitter example.")

If the restriction is intentional, keep it and ask the agent to work within it. If you want the agent to access this file, change the relevant control deliberately. A visibility change applies to new container agent sessions; an existing session’s access does not change.

If neither control explains the problem, inspect the agent’s error and the workspace it is using. See [Inspect the agent’s work](#inspect-the-agent-run).

<a id="section-2"></a>

## Verification has no usable result

Open **Issues** and read the verification status before deciding what to do. A check that could not finish is **not a passing result**, and it is different from a rule that failed against your code.

| Status or message | What to do next |
| --- | --- |
| **Analyzing code** or **Checking rules** | Follow the current stage. Wait for it to finish before interpreting the result. |
| **Not indexed yet** or **Couldn’t index this project** | Follow the card’s action to start indexing or **Retry**. Panolayer needs to read the sources before it can verify them. |
| **Verification was interrupted** or **Verification needs attention** | Read the accompanying error, address its cause, then choose **Retry** on the status card. |
| **Couldn’t read verification status** | Choose **Retry** to read the status again. The message does not establish whether the code passed or failed. |
| **Undecided results** | Open the recorded reason for each item. These checks are neither passing nor failing. |
| **Input too large** | Retrying unchanged inputs will not help. Include the affected file and visible message in a report so the team can investigate. |
| **Evaluation could not finish** | Address the recorded cause, then use **Retry check** where offered. |
| **Nothing to verify — no changes yet** | The agent has no changes to check. Inspect its task and workspace before expecting a merge result. |

If the app reports that an agent workspace was removed or is not being tracked, choose **Return to main** to continue working in the main workspace. An old result does not establish the status of files that are no longer being checked.

After a retry, read the new status. Do not treat a disappeared error, an empty issue list, or an unfinished check as proof that the code passed. See [Understand a verification result](/docs/verification-results).

<a id="section-3"></a>

## A rule looks wrong

Open **Details** beside the issue and compare the expectation, explanation, and source. In the Twitter example, `clearSaved` is expected to finish only after bookmark removals complete; the details show why its current code returns too early.

![Expanded issue details for clearSaved and clearAll in SavedPosts.tsx, showing the expected behavior, why each rule failed, and source-line evidence.](/docs/first-bug/03-issue-details.png "Details connects a failed expectation to the affected function and source lines. Use your own repository’s intended behavior to assess the result.")

- **The expectation is right and the code violates it:** choose **Fix** and select **Panolayer Agent** or another installed agent. Follow [Fix your first bug](/docs/first-bug).
- **The expectation describes the wrong behavior:** correct the rule so it matches what the function should do, then run verification again and inspect the new result.
- **The expectation is right but the reported failure appears incorrect:** report the rule, the visible explanation, and a minimal example that reproduces it.

Changing an expectation is different from fixing the code. Do not weaken an accurate rule just to turn a failure into a pass.

<a id="inspect-the-agent-run"></a>

## An agent stops, or you can’t find its changes

Open **My Agents** and return to the conversation for that task. Choose **Open** on its run card. In **Stream**, select the relevant activity to inspect the command and its output in the right-hand panel. Read the error before sending another task.

**A command or test failed?** Check what the output actually says. A missing dependency, a rejected credential, and a failing application test need different fixes. Give the agent the failing command and the result you expect, keeping the follow-up tied to the same task. If the app shows a failure card, use its **Technical details**, **Retry**, or **Report a bug** controls.

**The agent finished, but your checkout looks unchanged?** Coding work happens in the **agent’s worktree**, separate from your main workspace. Open **Changes** and select that agent’s worktree on the right-hand side to see its uncommitted code. You can review worktrees, inspect changes by risk, and commit from Changes.

**The run says Done, but the work is not merged?** Completion and merge approval are separate. Review the verification summary and changed files, then decide whether to merge. A merge into your branch records the change locally; pushing to your remote is a separate step.

See [Follow the agent’s work](/docs/running-agents#follow-the-work) and [Review changes and commit](/docs/changes).

<a id="graph-step-fails"></a>

## A graph step fails or the answer is incomplete

Inspect the step that failed and its output before changing the whole graph.

| What you see | What to check |
| --- | --- |
| The graph is read-only | Duplicate the built-in graph to edit your own copy. |
| An agent step needs a classification | Select the step and choose its agent classification in the right-hand panel. |
| A script fails immediately | Check **Program**, one argument per line, and **Success exit code**. The program must be available where the step runs. |
| The agent doesn’t use the question from this run | Check that **Custom instructions** includes the **Goal** variable inserted with **@**. |
| A failure has nowhere to go | Inspect the red failure route and connect an explicit handler or **Failed** destination. |
| The graph succeeds but the answer is incomplete | Read the agent step’s output, clarify its instructions, and test the same goal again. |

A successful script step means it met its configured success exit code. Check the actual output and the result you intended, too. After editing a failure route, test that path deliberately.

Follow [Build your first AI agent graph](/docs/graphs/first-graph#troubleshooting) for the working example and configuration screenshots.

<a id="merge-and-push"></a>

## A merge conflicts, or a push fails

**Start in Changes.** Select the relevant worktree and inspect what is waiting to be committed or merged. If you already approved an agent merge, find its commit in **History** before trying to commit the same work again.

**If the merge reports conflicts:**

- Read the conflict dialog. The agent’s work has not been merged yet, and its worktree remains available.
- Resolve each conflicted file in the **agent’s worktree**, save it, and stage that resolution with `git add` in that worktree. You can also use the dialog’s action to ask the agent to resolve the conflicts, then review its edits.
- Choose **Refresh status**. If the rebase is paused and the conflicts are staged, choose **Continue rebase**.
- Review the resulting changes, then use **Review & retry merge** when offered.

Do not resolve a conflict in a different checkout and expect the agent’s worktree to change with it.

**If a push fails:** read the Git error and check the configured remote and your permission to write to it. If the remote branch has moved on, reconcile the changes using your normal Git workflow before retrying. A local merge or commit remains local until a push succeeds. The Twitter sample may have no remote configured; a local commit is enough to complete its walkthrough.

See [Review changes and commit](/docs/changes#push) for commit, History, and push controls.

<a id="section-5"></a>

## Report a bug

If the problem persists, choose **Report a bug** in Panolayer, or [contact the team](/contact). When an agent fails, use **Report a bug** on its failure card so the report includes that agent’s diagnostics.

You can use this template:

```text
What I was trying to do:
Steps to reproduce:
1.
2.
3.
Expected result:
Actual result:
Exact error or status:
Panolayer version:
Mac chip and macOS version:
Agent name, if relevant:
Does it also happen in the Twitter Clone sample?
```

Include the file or function name when it helps locate the problem, and note whether it happened in the main workspace or an agent worktree. A small example you can share is more useful than an entire private repository. You don’t need to test the sample if it would interrupt your current work.

The report dialog includes diagnostics and logs, and can attach the current screen. Review the **Screenshot attached** control and any files you add before sending. Leave out credentials, API keys, and private source code you do not intend to share.

After sending, keep the **tracking reference** shown in the confirmation so you can refer to the same report when following up.

## Continue learning

- [Install and set up Panolayer](/docs/getting-started)

- [Supported agents](/docs/agents)

- [Understand a verification result](/docs/verification-results)

- [Build your first AI agent graph](/docs/graphs/first-graph)

- [Review changes and commit](/docs/changes)
