Troubleshooting

Test Connection

Message	Fix
Please save your GitHub PAT first.	Save the form, then test.
Authentication failed. Your PAT may have expired.	Create a new token and paste it in.
Permission denied. Ensure your PAT has the required scopes…	Give the token Contents and Pull requests read and write on this repo.
Repository not found. Check that your PAT has access to the repo.	Check the URL, and that the token's repository access includes this repo. GitHub Enterprise and GitLab aren't supported.
Cannot parse GitHub owner/repo from: …	Use https://github.com/owner/repo. Repo names with a dot aren't supported.
GitHub API rate limit exceeded.	Wait the number of minutes shown.
Could not fetch branches from GitHub.	Save the Repository URL and token, then reload the form.

Settings

Message	Fix
Duplicate DocType 'X' in row N.	Remove one of the rows.
Invalid JSON in filters for 'X' (row N).	Fix the JSON. Keys and text need double quotes.
Filters for 'X' (row N) must be a JSON object…	Wrap it in { }, such as {"module": "HR"}.
Filters for 'X' (row N) won't run: …	The field or operator doesn't exist on that DocType. Fix the name.
Remote 'custom-migrator' has no branch '…' (Initialize Git)	Pick the right Base Branch before initializing.

The Custom Migrator page

Message	Fix
Choose a Target App to begin	Set up Migrator Settings.
Failed to Load Items	You can't read one of the ticked types (Server Script needs the Script Manager role), or its filter is wrong.
Please select items to migrate	Tick at least one record.
This action is only allowed for System Manager, Hydra Admin (on + Add)	Ask an admin to add the DocType.
A count in the sidebar is higher than the rows in the list	The list shows at most 500 records per type. Narrow it with a filter.

Commit and push

Message	Fix
Invalid branch name	Use letters, numbers, ., _, - and / only.
'…' has no .git directory	Use Initialize Git Repository in Migrator Settings.
Cannot create branch from 'custom-migrator/…'	The base branch doesn't exist on GitHub, or you picked the base branch itself. Check Base Branch, and push to a new branch.
Customisation validation failed: … does not have a module key / is associated with another app	Open the record in Customize Form, set Module to one of your app's modules, and push again.
Customisation validation failed: … contains custom permissions	Custom permissions can't be exported. Remove them from the selection.
Corrupt JSON in …	A file in the app was edited by hand and is broken. Fix or delete it, then push again.
Authentication failed for …	The token expired or lost access. Run Test Connection.
Push Timeout	The push is still running. Check the Migration Log.
PR Creation Failed: Permission denied	The token can push but can't open pull requests. Your branch is pushed, so open the pull request on GitHub, and add Pull requests: Read and write to the token.
PR Already Exists	Open the existing pull request from the link.

Limits

• GitHub.com only.
• Up to 500 records per type on the page. Search covers the current page only.
• A push runs for up to 5 minutes. The browser stops waiting after about 3.
• No automatic undo, and deletions aren't carried over. See Apply on other sites.

Known issues

We're working on these. Until they're fixed:

• A push to an existing branch can report success when GitHub rejected it. It happens when someone else has pushed to that branch in the meantime. Push to a new branch (the default) to avoid it, and check the pull request on GitHub.
• The Export Preview can disagree with the push. The preview compares with the copy of the app on the server, while the push compares with GitHub. If the server copy is behind, an item can show as changed but push as "Already up to date", or the other way round.
• The Failed shortcut in the Migration Log filter shows nothing. Filter by Status = Failed instead.
• bench export-fixtures can fail on an app Custom Migrator has pushed to, because of the entries it adds to hooks.py. Custom Migrator itself isn't affected.
• A release tag that already exists fails the push after the branch was already pushed. Use a new tag.
• The empty list says "click Show All". There's no such button: tick a type in the sidebar.

Still stuck?

Click Feedback on the Custom Migrator page and choose Bug. Or ask on Slack.