Troubleshooting

Anything not listed here: check the Migration Log row's error_message field and the Frappe Error Log.

Test Connection

Error	What to do
No GitHub PAT configured (save the form first if you just pasted one)	Save Settings after pasting the PAT, then retry.
No target app selected	Pick a Target App in Settings.
Could not locate target app '<app>': ...	The app isn't installed. Confirm with bench list-apps.
Could not get remote URL for '<remote>' in '<app>'	Run git remote -v in apps/<app>. Either update Remote Name in Settings or git remote add the missing remote.
Cannot convert remote URL to HTTPS: ...	Remote URL must be https:// or git@. Edit it in Settings.
Authentication failed. Check your PAT scopes ...	PAT expired, revoked, or missing scope. Reissue with contents:write + pull_requests:write.

Success format: Authenticated to <url> (<N> branches found).

Initialize Git Repository

Error	What to do
Please enter a Remote URL first.	Fill Remote URL in Settings, then click the button.
Remote '<remote>' has no branch '<base_branch>'. ...	Either change Base Branch in Settings, or push that branch to the remote first.

PR creation

Dialog title	Colour	What it means	What to do
PR Creation Failed	orange	Push succeeded but the PR API call didn't. Usually missing pull_requests:write scope.	Reissue PAT with that scope, or open the PR manually using the branch link in the success banner.
PR Already Exists	blue	Another process opened a PR for this branch first.	Click Open Existing PR #N — your commits are on it.
Pushed to Existing PR	green	Not an error. Your push landed on a branch with an open PR.	Click View PR #N to see it.

On the target site

Pushed customisation doesn't show up after bench migrate — Frappe caches DocType metadata. Clear it:

bench --site <site> clear-cache

Then hard-refresh the browser (⌘⇧R / Ctrl+Shift+R).