Troubleshooting

Start with pointfix doctor: it checks Node, your configuration, the port, agent sign-in and platform tools. The sections below cover what it can’t see.

Bridge

The port is busy

doctor reports Port 4747 is in use by another program, or Port 4747 serves another project when another Pointfix bridge is running there. Stop that program or bridge, or pick another port with "port" in pointfix.config.json (or pointfix start --port=4848). Use the same port in your SDKs, adb reverse and the Mac app.

“Project already locked”

Only one bridge runs per project. If start says Project already locked at … (PID 1234), either a bridge is still running for this project, or one exited without cleaning up. Pointfix never removes the lock for you.

1. Check whether that process still exists: ps -p 1234.
2. If it is a running bridge, stop it (Ctrl + C in its terminal).
3. Only if the PID is gone, delete the lock file named in the message (it is in the project’s .pointfix folder) and start again.

The dashboard can’t save settings

Open it at http://127.0.0.1:4747, not http://localhost:4747. Only the 127.0.0.1 origin may change settings and act on reports.

Reports show “Interrupted” after a restart

Queued and running reports become Interrupted when the bridge stops, so unfinished work is never repeated silently. Check the files the agent touched, then use Retry run, Resolve manually. Revert isn’t available for interrupted runs, so undo unwanted edits yourself.

“Not a Git repository”

Without Git, reports still run, but Pointfix can’t list, diff, commit or revert the agent’s changes, and the repository search for source matches is skipped. Run git init in the project, or review and commit by hand.

Agents

The agent isn’t signed in

Claude Code and Codex runs fail before any model call if the CLI isn’t signed in with a subscription: Claude Code is not signed in with a Claude subscription… or Codex is not signed in with ChatGPT…. Run claude auth login or codex login, then pointfix doctor. To use API keys instead, set "useApiKeys": true. See Subscriptions and API keys.

“… isn’t installed: … is not on PATH”

The bridge only finds agents on the PATH it was started with. Install the CLI, make sure it runs in the same terminal, then restart the bridge.

The run failed

Open the report’s Activity tab and read the agent output. Check that the CLI works in Terminal from your project folder. Codex expects a trusted repository; Claude Code’s project permissions can deny commands in print mode, and with Lean runs it only has file tools. Pointfix does not turn off the agents’ permission controls. A step that runs longer than agentTimeoutMs (30 minutes by default) fails as timed out.

The app didn’t restart

Check that Auto-relaunch is on, then read the run log: it says when relaunch was skipped and why. iOS needs the Xcode project and scheme in Preferences → Relaunch targets and a report from a simulator; Android needs the application ID. For anything else, set workflow.relaunch to a script that builds and launches your app. A failing workflow.check also skips relaunch.

iOS

No composer appears

Run a Debug build in the iOS simulator, with .pointfixHost() applied once at the window root, and hold the element for at least 0.6 seconds. Capture is compiled out of Release builds and is not available on physical devices. If a sheet or full-screen cover is open, dismiss it and try again.

“Couldn’t reach Pointfix” or “Bridge unreachable”

Start the bridge, open the dashboard to confirm it runs, and pass the same port to the host (.pointfixHost(port:)).

Element context is missing

Give the control an accessibilityIdentifier, or add .pointfixable for an exact file and line. For more context from SwiftUI, install AXe or set POINTFIX_AXE to its executable.

Simulator panel

Accessibility access isn’t detected

If the panel keeps showing Allow Accessibility access although Pointfix is turned on in System Settings, the entry in System Settings belongs to a different copy of the app, for example one you replaced or moved.

1. Quit Pointfix.
2. Reset its permission: tccutil reset Accessibility dev.pointfix.mac
3. Open Pointfix, choose Open System Settings in the panel, and turn Pointfix on in Privacy & Security → Accessibility.

The panel doesn’t appear

Check View → Simulator Panel (⇧ ⌘ P) and that a Simulator device window is open, not minimized and on the current Space. The Mac app must be running.

Android

Reports don’t arrive from the device

• Run adb reverse tcp:4747 tcp:4747 again: reconnecting the device or restarting the emulator removes it. Add -s SERIAL when several devices are attached.
• Allow cleartext HTTP in your Debug manifest (android:usesCleartextTraffic="true"). An existing network security configuration can override it.
• The pill’s message names the likely cause: Check the bridge and adb reverse, or for a remote bridge, that it runs with "remote": true.

The emulator can’t reach a bridge on another Mac

Android emulators often can’t resolve .local names. Use the other Mac’s IP address from its Connections page, such as http://192.168.1.20:4747.

“This screen prevents screenshots”

Screens with FLAG_SECURE can’t be captured.

Web

“Origin is not allowed”

Add the page’s exact origin (scheme, host and port, such as http://localhost:5173) to allowedOrigins and restart the bridge. localhost and 127.0.0.1 are different origins.

Parts of the screenshot are missing

html2canvas redraws the page and can omit cross-origin images, iframes, video, canvas content and unsupported CSS. The report still includes the element’s DOM context.

The script doesn’t load

A Content Security Policy must allow the bridge’s origin in script-src and connect-src. Pages served over HTTPS can block the HTTP bridge as mixed content. If the screenshot library fails to load from the bridge, reinstall Pointfix with brew reinstall pointfix-dev/tap/pointfix.