FAQ & troubleshooting

Find the fix. Fast.

When something goes wrong

Find your error message below.

Invalid URI: The hostname could not be parsed.▾

Why: You pasted two commands at once into PowerShell. PowerShell's curl is different.

Fix: Go back to Step 2 and paste each of the three blocks separately.

'node' is not recognized as an internal or external command▾

Why: Node.js isn't installed, or the terminal was already open when you installed it.

Fix: Install Node.js, then close and reopen PowerShell / Terminal. Verify with node --version.

Permission denied (publickey)▾

Why: Your SSH key isn't on GitHub, or it doesn't have push access to the destination repo.

Fix: Redo the SSH key section above, then run ssh -T git@github.com.

Helper pill stays "offline" in the panel▾

Why: The helper window was closed, or the agent URL is wrong.

Fix: Re-run node gitlove-agent.mjs start. In Setup, the Helper URL should be http://127.0.0.1:7878.

fatal: repository not found▾

Why: Destination repo doesn't exist yet, or your SSH key lacks push access.

Fix: Create the empty repo at github.com/new first.

Errors about LFS / large files▾

Why: Git LFS isn't installed on your machine.

Fix: Install Git LFS (git-lfs.com), then run git lfs install once.

Windows SmartScreen blocks gitlove-agent.mjs▾

Why: Windows is cautious about files downloaded from the internet.

Fix: Click More info → Run anyway. The file is plain JavaScript — you can open it in Notepad to inspect.

macOS says "node: command not found" after installing Node▾

Why: Terminal was open during install and didn't pick up the new PATH.

Fix: Close Terminal completely (Cmd-Q) and reopen it.

Source/destination picker is empty — no repos listed▾

Why: You haven't connected your GitHub account yet, so GitLove has no repo list to show.

Fix: Open the side panel → Setup → GitHub account → paste a token. See Step 4 above.

Start mirror button does nothing / says "Helper not connected"▾

Why: The helper window on your computer isn't running, or the pairing token in Setup is wrong.

Fix: Re-run the helper command from Step 2, then check the green dot at the top of the side panel and the pairing token in Setup.

Glossary

Plain-English definitions of the terms you'll see in this guide.

SSH URL▾

The address format git@github.com:owner/repo.git. GitLove uses SSH so your computer can push to GitHub without typing a password.

SSH key▾

A pair of files on your computer that prove you own your GitHub account. You create one once and paste the public half into GitHub (see the SSH key section above).

Personal Access Token (PAT)▾

A password-replacement string that lets apps call GitHub's API as you. GitLove only uses it to read the list of your repos.

Helper▾

The small program (gitlove-agent.mjs) you start in a terminal window. It runs git on your behalf and listens only on 127.0.0.1.

LFS (Large File Storage)▾

GitHub's add-on for files bigger than ~100 MB. If a repo uses LFS, GitLove can mirror those files too — just leave the checkbox ticked.

Mirror▾

A complete copy: every branch, tag, commit, and (optionally) LFS object — pushed from a source repo to a destination repo.

Pinned destination▾

A repo you save once in Setup so you can pick it as a destination with one click in the side panel.

FAQ

Is my code uploaded to your servers?: No. The helper runs on your computer and pushes directly to GitHub over SSH. GitLove never sees your code.
Why does GitLove need a GitHub token?: Only to show your repos in a searchable list so you don't have to type a repo URL. The token is stored in your browser only, used to call api.github.com to read your repo list, and never sent anywhere else. You can revoke it any time from GitHub.
What scope does the token need?: Classic tokens: the 'repo' scope. Fine-grained tokens: Contents → Read-only on the repos you want to mirror. The token is never used to push code — pushes happen over your SSH key.
Is there a repo size limit?: No. There's no API rate limit and no upload cap — GitLove uses your own git, git-lfs, and SSH connection. The only practical limits are your disk space (for the temporary clone) and GitHub's own per-push guidance.
Do I need to keep the helper window open?: Yes — only while mirroring. Close it any time after.