troubleshooting

Troubleshooting

Python is not recognized

python --version   # or python3, or py -3

• Install Python 3.10+ from python.org or winget install Python.Python.3.12.
• Restart the terminal so PATH updates.
• If only python3 is available (Linux/macOS), use python3 in every command.

Git is not recognized

git --version

Install Git and restart the terminal. URGithub runs Git through the PATH.

GitHub CLI is not recognized

gh --version

Install GitHub CLI (winget install GitHub.cli, apt install gh, or brew install gh) and restart the terminal.

Authentication check fails

gh auth status

If not logged in, authenticate:

gh auth login

The setup wizard's authentication step must report that you are logged in successfully. Choose the login flow that matches your setup (device flow for SSH/remote sessions).

Commits fail with "user.name" / "user.email"

git config --global user.name "Your Name"
git config --global user.email "you@example.com"

Git refuses to commit without an identity.

Synchronization is blocked

Do not bypass the safety mechanism immediately. First inspect report.html and check for:

• divergence
• detected secrets
• invalid repository state
• missing remote
• authorization failure
• repository access failure
• unsupported state

flowchart TD
    A[Repo not pushed] --> B{Blocked?}
    B -->|blocked: divergence| D[git pull manually and review]
    B -->|blocked: secrets| E[Remove / gitignore the secret, or add to security.allow_files]
    B -->|blocked: oversize files| F[Remove file / move to LFS / raise limits.max_file_mb]
    B -->|blocked: no push permission| G[Check gh auth scopes, repo permissions]
    B -->|blocked: no remote configured| H[Add origin remote]
    B -->|skipped| I[Enable commit_policy.auto_commit or commit manually]

Loading

A blocked operation is often an intentional safety result. Resolve the cause — e.g. remove the secret file, fix the remote, or review a divergence manually — then rerun. For diverged repos, resolve the merge yourself; URGithub never does it for you.

GUI does not open

python -c "import tkinter; print('tkinter OK')"

If this fails on Linux, install the Tk package for your distribution (e.g. python3-tk). The wizard and Control Center require tkinter.

Scheduled task does not run (Windows)

python urgithub.py --schedule status

Reinstall the schedule and check the registered tasks:

python urgithub.py --schedule install

The shutdown quick-push task requires admin rights — run the install that triggers the UAC prompt. Confirm the tasks appear in Task Scheduler and that the Python path stored in the task is correct.

Scheduled run fails on Linux/macOS

Cron and launchd jobs run with no terminal PATH. Use absolute paths:

0 */3 * * * cd /home/you/push-to-github && /usr/bin/python3 urgithub.py --run scheduled

Confirm the real interpreter path with which python3.

A run says "skipped — lock held"

Another run is active; the global lock serializes them and the second one exits. A stale lock expires after 15 seconds.

Two runs fire at once

Impossible by design — the global lock serializes them; the second one exits.

--schedule status is empty

Run python urgithub.py --schedule install first (requires registration).

Shutdown task is not created

Run --schedule install from an elevated prompt (the wizard retries with a UAC prompt automatically).

Repo names out of sync with GitHub

GitHub is the source of truth for names:

• Renamed on GitHub only → URGithub detects it via gh api and renames the local folder + registry entry automatically.
• Renamed locally only → URGithub adopts it, reusing the registry entry. Then run gh repo rename NewName --repo owner/OldName on GitHub to match.
• Leftover ghost entries (from manual moves) can be dropped with --forget NAME or bulk-cleaned with --prune.

Missing repositories

• Run python urgithub.py --scan then python urgithub.py --repos to see what is discovered.
• Reconciles against gh repo list — check the github_owner setting and gh auth status.
• Forked repos are skipped when skip_forks is enabled.
• New clones require clone_missing_repos to be enabled (default).

Reporting a problem

Open report.html for the failed run and include:

• the trigger that started the run
• the repositories and operations involved
• the failure / blocked reason from the report
• relevant journal entries (journal.jsonl)
• your platform and Python/Git/gh versions

Back to Home.