docs

Troubleshooting

The few things that go sideways, what PullMark's messages mean, and the design behind the quieter failures — most "errors" here are the app deliberately refusing to lose your work.

GitHub access: how PullMark connects, and fixing it

PullMark borrows the GitHub credentials your own tools already have — it has no login of its own and never stores a secret. Settings → General → GitHub shows whether it's connected, as whom, and through which source; Set Up… walks a new machine through connecting, and Check Again picks up a fix immediately — after gh auth login, no relaunch needed.

Reading this on the Mac where PullMark (0.36+) is installed? Open the connection row now.

The credential sources, in the order PullMark tries them:

  1. The GitHub CLI's token: gh auth token must print one. If not, brew install gh && gh auth login — the recommended path: its token has known-good scopes, handles SSO in the browser flow, and refreshes.
  2. Otherwise git credential fill — whatever git itself uses for github.com (macOS keychain, Git Credential Manager, a token stored by an old HTTPS push).

Token fine print, for tokens that half-work: classic tokens need the repo scope (and read:org for org team names); fine-grained tokens are bound to one resource owner — public repos and that owner's private repos work, everything else is denied; SSO-protected orgs need the token authorized for each org; and manually created tokens expire — the Settings row is where "worked yesterday" gets diagnosed.

GitHub: "may not exist… or may be a private repository"

"Couldn't open … It may not exist at that ref, or it may be a private repository your GitHub credentials can't access." GitHub's API reports private-without-access and doesn't-exist identically, so PullMark can't tell you which. If the repo should work, it's almost always authentication — see GitHub access above, or open Settings → General → GitHub and hit Set Up….

Gatekeeper won't open the app

Releases are signed with a Developer ID and notarized by Apple, so a normal download shows no warning. If you built from source (make app), the app is ad-hoc signed: right-click → Open → Open, or allow it under System Settings → Privacy & Security.

Quick Look previews stopped rendering

A Homebrew upgrade replaces the app bundle, which can silently drop the Quick Look extension's registration. PullMark re-registers it on every launch — so just launch the app once. If previews still show raw text, check Settings → General → "Quick Look previews" is set to Rendered.

"PullMark is no longer your default Markdown app"

Same cause: an upgrade replaced the bundle and macOS dropped the .md binding. The banner's Make Default Again reclaims it; so does Settings → General.

"… changed while you were editing this block — nothing was saved"

The file changed on disk (another editor, an agent, a git operation) between opening the block editor and saving. PullMark refuses to splice into lines that moved — nothing is lost except the one edit, and re-opening the block shows the current text. The same guard protects commits: comparing against a ref where the file doesn't exist reports it plainly instead of showing an empty diff.

Dimmed rows: folders and recents that "aren't there"

A Location with a question-mark badge, or a grayed recent, means the path doesn't resolve right now — an unmounted volume, a switched git branch, a deleted worktree. Rows dim instead of vanishing on purpose: they revive automatically when the path returns. Clicking a dead recent offers Remove from Recents or Keep.

Pull requests: banners and pending comments

  • "This pull request was updated on GitHub." — the branch moved since you loaded it. Refresh is one click and your draft comments survive; PullMark never auto-reloads under an in-progress review.
  • "Review comments couldn't be loaded…" — the diff would otherwise masquerade as an uncommented PR; Retry refetches.
  • "Could not upload N pending comment(s)… kept locally for retry." — comments written offline (or through an API hiccup) queue on disk per PR-head and upload when they can. Nothing is dropped.
  • "Committed …, but the push failed" — the commit is safely in your local history; only the push needs retrying.

Updates

The banner's Update Now runs the brew upgrade (or a verified in-place install for DMG installs) and relaunches. If it fails, the banner shows the exact brew upgrade --cask pullmark command with a Copy button — running it in a terminal does the same thing. Development builds don't check for updates.

The pullmark command

  • "no such file or folder" — the command verifies every path before opening anything; one typo aborts the whole open (exit code 1) so scripts fail loudly.
  • Command not found — see installing the command.
  • "Couldn't install the command" — the Settings installer needs authorization to write /usr/local/bin; cancel and rerun if you dismissed the prompt.

Still stuck?

Open an issue — Help → Report a Bug… pre-fills one from inside the app.