Troubleshooting
Fixes for the problems people run into most often.
Start here
Section titled “Start here”Run glasstarn doctor in a Terminal, or ask your agent to run it. It checks the version, the connected agents, any running results page and your project folders, and gives one fix for each problem.
Install
Section titled “Install”My AI app says it cannot run commands. glasstarn needs an AI app that can run commands on your computer. In the Claude and ChatGPT desktop apps, use the coding or agent mode (Claude Code, Codex). A chat in a web browser cannot install it.
It says Node is missing or too old.
glasstarn installs with npx, which comes with Node.js. Node.js 18 or newer is required. If you need to install it, choose the current LTS release from nodejs.org, then try again.
At work, the install is blocked. Your company may control what can be installed. Ask your IT team to approve Node.js and the glasstarn package. Everything runs on your computer, which usually makes approval easier.
Starting
Section titled “Starting”My agent does not know about glasstarn.
Restart your AI app after installing, then ask it to use glasstarn. In Claude Code you can also type /glasstarn; in Codex, $glasstarn. If it still does not know it, ask the agent to run npx glasstarn setup again.
The browser view does not open.
Ask your agent to “open the glasstarn view”. The address starts with http://127.0.0.1. glasstarn stops by itself after a while unused and gets a new address when it starts again, so a bookmark from an earlier day may not work. Ask for a fresh link.
The page says it cannot reach glasstarn. glasstarn stopped, often because the computer went to sleep or the AI app was closed. Ask your agent to start it again.
Importing
Section titled “Importing”My file will not import. Check that it has a column for the item, the step and the time. If the file is a report with titles, merged cells or totals rows, export the raw table instead. Your agent will tell you what it could not read.
The dates look wrong.
A date such as 03/05/2026 can mean 3 May or 5 March. glasstarn asks you which one under Data checks. If you answered wrongly, ask your agent to change the date format and refresh.
Some records were left out. That was a choice under Data checks. The records left out are listed as a finding on the Overview. You can ask your agent to keep them instead.
Results
Section titled “Results”The map is a mess. Move the Activities and Connections sliders to the left, or choose Main flow. Busy processes have many rare routes, and you rarely need to see all of them at once.
The numbers look too good, or too fast. Items that were not finished when the export was made can make times look short. Add the filter Leave out incomplete items.
A page shows fewer items than I expect. A filter is on. Look for chips at the top of the page and select Clear all.
I cannot export BPMN. It only works in Classic view. Switch the map from Subway to Classic.
I asked my agent to show something, but the page did not change. The page follows your agent’s answer within a few seconds while its tab is showing. If you closed the tab, ask again and your agent opens it on the same view and filters. If the page was open from before an update, your next question restarts it on the new version.
Agent connection
Section titled “Agent connection”My agent says it has no access to the project. In the browser view, select Connect an agent at the top, choose what it can see, then Allow access. If you turned access off earlier, turn it on again.
After a restart, my agent lost the connection. Open the project again in the browser view, then retry in your agent. If that does not work, restart your AI app.
Still stuck?
Section titled “Still stuck?”Email hello@glasstarn.com, or open an issue on GitHub, with what you tried and what you saw. Leave out any company data.