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 |
| The browser signs in, but the app is still waiting | Finish sign-in |
| Your repository won’t open or looks incomplete | Open the right repository |
| An agent is missing, won’t launch, or reports an engine error | Start an agent |
| An agent can’t read or modify a file | Check file access |
| Verification is interrupted, unavailable, or undecided | Recover verification |
| A rule describes the wrong behavior | Inspect the rule and its evidence |
| An agent stops, or you can’t find its changes | Inspect the agent’s work |
| A graph fails or returns an incomplete answer | Check the graph step |
| A merge conflicts, or a push fails | Resolve merge and push problems |
| You still need help | Report a reproducible bug |
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.
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.
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 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.
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 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.
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.
- Check Supported 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.
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.
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.
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 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.
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. |
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.
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.
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.
- The expectation is right and the code violates it: choose Fix and select Panolayer Agent or another installed agent. Follow Fix your 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.
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 and Review changes and commit.
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 for the working example and configuration screenshots.
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 addin 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 for commit, History, and push controls.
Report a bug
If the problem persists, choose Report a bug in Panolayer, or contact the team. 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:
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.