Troy / Project
Troubleshooting
Fixes for common Troy problems: Homebrew and first launch, missing or stale endpoint files, failed attaches, page reads, extensions and the action scripts.
On this page
- Homebrew refuses to load the cask
- macOS says Troy cannot be opened
- macOS says Troy is damaged
- Windows SmartScreen blocks the installer
- An old version keeps launching
- agent-endpoint.json is missing
- agent-endpoint.json exists but nothing answers
- The attach fails or finds no page
- A script closed my browser
- The read script cannot find Troy
- The read script reads the wrong tab, or none
- A read shows “untranscribed” regions
- A read says the page never settled
- A selector from a read does not work
- Troy says “Something went wrong inside Troy”
- “Troy will not open that”
- A site needs the camera, microphone or location
- An extension did not load
- Remember history does nothing
- Action script problems
- Tests fail with a corrupt or missing Electron
Problems are in the order you are likely to meet them: installing, attaching an agent, reading pages, using the browser, the action scripts, and running the tests.
Homebrew refuses to load the cask
Refusing to load cask velofy/tap/troy from untrusted tap velofy/tap means the tap is not trusted yet. Homebrew 7.0 requires that once per third-party tap:
brew trust velofy/tap
brew install --cask velofy/tap/troy
brew trust --cask velofy/tap/troy trusts only this cask.
macOS says Troy cannot be opened
Troy is ad-hoc signed but not notarised. For a disk image (DMG) you downloaded yourself, Control-click Troy in Applications and choose Open. You only need to do this once. Installing with Homebrew avoids the prompt, because the cask clears the quarantine flag.
macOS says Troy is damaged
This is what a bundle with a broken signature looks like on Apple silicon, and Control-click then Open does not fix it. Release builds are ad-hoc signed and verified during packaging to prevent it. If you packaged Troy yourself, make sure scripts/after-pack.cjs ran; the build output shows “ad-hoc signed and verified” when it did.
Windows SmartScreen blocks the installer
Choose More info, then Run anyway. The builds are not code signed.
An old version keeps launching
release/ in a source checkout is a build directory. If a search tool indexed an old build there, launching it runs that build. Install from Homebrew or a release, or run npm run clean. Every npm run dist:* clears the folder first.
agent-endpoint.json is missing
Troy is running without the agent port. Quit it and start it again with --cdp-port=<port> or TROY_CDP_PORT. On macOS, open -a Troy --args ... brings an already running Troy to the front instead of restarting it, so quit Troy first. The file is also deleted on every quit.
Check that the port value is an integer from 1 to 65535 and is written as --cdp-port=9333, with the equals sign. Troy ignores a bad value silently.
agent-endpoint.json exists but nothing answers
The file outlived the browser, or belongs to a different copy:
- Troy crashed or was force quit. The file is deleted only on a normal quit. Delete it and start Troy again with the port.
- Two copies share the profile. Troy has no single-instance lock. The second copy overwrites the file and deletes it when it quits. Run one Troy.
To check, request /json/version on the httpEndpoint in the file. A live Troy answers; a stale file gets a refused connection.
The attach fails or finds no page
- Confirm the port in
agent-endpoint.jsonand connect to itshttpEndpoint. - The connection must come from the same machine. Troy allows Chrome DevTools Protocol (CDP) connections from the
http://127.0.0.1origin. - Filter pages on
p.url().startsWith('http'). Troy’s chrome and new tab page arefile://pages. - A tab that has never been shown can report empty
innerText. Bring it to the front, or readtextContentknowing it includes hidden text.
A script closed my browser
It should not. browser.close() on a connectOverCDP connection detaches. If Troy closed, check whether the script called something that quits the app, or closed tabs it did not open.
The read script cannot find Troy
read: no agent-endpoint.json at <path> means the script looked in the wrong place, or Troy is running without the port.
- On Linux the script’s default path is the macOS one. Set
TROY_ENDPOINT_FILE="$HOME/.config/Troy/agent-endpoint.json". - Otherwise start Troy with
--cdp-port=9333.
The read script reads the wrong tab, or none
read: no open tab matches <address>:--urlmust equal the tab’s address exactly, including a trailing slash. It does not open the address. Copy it from the address bar.read: no http tab is open in Troy: onlyhttpandhttpstabs are read. Troy’s new tab and failure pages are local files.- Without
--url, the script takes the last web tab in Playwright’s list, which may not be the one in front. Pass--url. read: no open tab matches --json(or--out): another option was given without--url, and the script took it as the address. Add--url <address>.
A read shows “untranscribed” regions
[untranscribed canvas region, ...; no OCR engine available] is expected on main. The pipeline found a region only pixels can explain, such as a canvas, an image without alt text or a cross-origin iframe, and no optical character recognition (OCR) engine is connected yet. The marker gives the region’s size and position. Take a screenshot of that box if you need its contents.
A read says the page never settled
Settle waits up to 10 seconds for the page to finish loading, load its fonts and stop changing layout. A page with an animation, a live clock or an endless spinner never stops changing, so the read happens anyway after the deadline and is flagged. The text is usually still complete. From your own code, pass a different settleTimeoutMs to readPage.
A selector from a read does not work
Selectors that cross into a shadow root contain >>>. document.querySelector, which the action scripts and the agent tool layer use, rejects them. Pick an element outside the shadow root, or act on it from Playwright with a locator. Text from OCR blocks has no selector at all, because no element is behind it.
Troy says “Something went wrong inside Troy”
Troy caught an error that would otherwise have closed it. The browser stays usable. The details are in troy-errors.log in the profile folder (~/Library/Application Support/Troy on macOS). Include that entry when you open an issue.
“Troy will not open that”
The address uses a refused scheme, such as javascript: or data:. The notice gives the reason. This is intended and cannot be turned off. See Privacy and permissions.
A site needs the camera, microphone or location
Troy denies those permission requests by design. Use another browser for that site.
An extension did not load
Check that its folder is directly inside <profile>/extensions/ and contains manifest.json. Use View > Reload Extensions; the notice lists what loaded and the error for each failure. Electron implements only part of the Chrome extension application programming interfaces (APIs), so some extensions load but do not work.
Remember history does nothing
In v0.1.5 that is a known gap: the switch is stored but nothing records history. On main, visits are recorded in history.json in the profile while the switch is on. Nothing in the interface shows that list yet.
Action script problems
- “could not attach to a browser”: nothing is answering at
APPLY_FILL_CDP. Start the automation browser withnode scripts/launch.mjs, or pointAPPLY_FILL_CDPat Troy’s port. - “a browser is answering … but cannot be driven”: a stale process after the browser auto-updated. Run
node scripts/launch.mjs --force. - Several tabs match: pass
--url <substring>. - “authorizes no hosts”: the
generictarget needs--allow-host <hostname>. - Value does not stick (
fill.mjsexits 2): the site rejected or reformatted the input. Rundetect.mjsagain to see the field’s real value before retrying. - Field cap:
fill.mjsrefuses an answer longer than the field’smaxlengthrather than letting it be cut off. - NOT VERIFIED from
click.mjs: the click was sent but nothing observable changed. Treat it as a failure, narrow--within, or add an--expect-*check.
Tests fail with a corrupt or missing Electron
Fetch the binaries before running tests, as continuous integration (CI) does:
node node_modules/electron/install.js
npx playwright install chromium
Do not run test files in parallel; the config already runs them one at a time.