Skip to content
Troy

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
  1. Homebrew refuses to load the cask
  2. macOS says Troy cannot be opened
  3. macOS says Troy is damaged
  4. Windows SmartScreen blocks the installer
  5. An old version keeps launching
  6. agent-endpoint.json is missing
  7. agent-endpoint.json exists but nothing answers
  8. The attach fails or finds no page
  9. A script closed my browser
  10. The read script cannot find Troy
  11. The read script reads the wrong tab, or none
  12. A read shows “untranscribed” regions
  13. A read says the page never settled
  14. A selector from a read does not work
  15. Troy says “Something went wrong inside Troy”
  16. “Troy will not open that”
  17. A site needs the camera, microphone or location
  18. An extension did not load
  19. Remember history does nothing
  20. Action script problems
  21. 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.json and connect to its httpEndpoint.
  • The connection must come from the same machine. Troy allows Chrome DevTools Protocol (CDP) connections from the http://127.0.0.1 origin.
  • Filter pages on p.url().startsWith('http'). Troy’s chrome and new tab page are file:// pages.
  • A tab that has never been shown can report empty innerText. Bring it to the front, or read textContent knowing 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>: --url must 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: only http and https tabs 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 with node scripts/launch.mjs, or point APPLY_FILL_CDP at 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 generic target needs --allow-host <hostname>.
  • Value does not stick (fill.mjs exits 2): the site rejected or reformatted the input. Run detect.mjs again to see the field’s real value before retrying.
  • Field cap: fill.mjs refuses an answer longer than the field’s maxlength rather 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.