Troubleshooting

This page covers common GitBack issues and their solutions.

GitHub Authentication Failed

Example:

authentication failed
invalid token
unauthorized

Verify the token:

gitback doctor

Ensure the token has the required permissions.

Classic PAT:

repo

Fine-Grained PAT:

Contents: Read-only
Metadata: Read-only

If necessary, generate a new token and re-run:

gitback init

No Repositories Discovered

Run:

gitback discover

If no repositories are found:

• Verify GitHub authentication
• Verify repository access
• Verify organization membership if applicable

Validate the environment:

gitback doctor

No Gists Discovered

Run:

gitback discover

Verify:

• The account actually owns Gists
• The token is valid
• GitHub API access is working

Check:

gitback doctor

Repository Inventory Missing

Example:

repository inventory missing

Run:

gitback discover

GitBack will regenerate:

repositories.txt

Gist Inventory Missing

Example:

gist inventory missing

Run:

gitback discover

GitBack will regenerate:

gists.txt

Repository Sync Failed

Example:

repository unhealthy
sync failed

Inspect:

gitback health

Review logs:

~/.local/state/gitback/gitback.log

Common causes:

• Repository deleted
• Repository transferred
• Access revoked
• Network interruption

Refresh inventories:

gitback discover

Then retry:

gitback sync

Snapshot Creation Failed

Verify:

gitback health

Review:

• Disk space
• Repository failures
• Gist failures

If snapshot creation is blocked by failed assets:

gitback snapshot --force

Use force mode only after reviewing health information.

Low Disk Space

Example health output:

status: critical

Check:

gitback health

Actions:

• Increase available storage
• Enable snapshot retention
• Remove unnecessary snapshots

Example:

snapshot_retention: 30

Missing Directories

Example:

mirrors directory missing
state directory missing
snapshots directory missing

GitBack automatically recreates:

mirrors/
snapshots/
state/
tmp/

Recovery events are logged automatically.

No reinitialization is required.

Health Status Shows Warning

Example:

status: warning

Typical causes:

• Failed repositories
• Failed Gists
• Missing inventories
• Snapshot retention concerns

Inspect:

gitback health

Review recommendations included in the report.

Health Status Shows Critical

Example:

status: critical

Typical causes:

• Low disk space
• Storage issues affecting backup operations

Immediate action is recommended.

Inspect:

gitback health

and review available storage.

Verify Snapshot Integrity

Verify checksum:

sha256sum -c snapshot.tar.zst.sha256

Expected:

snapshot.tar.zst: OK

If verification fails:

• Re-transfer the snapshot
• Recreate the snapshot
• Check storage integrity

Log Location

GitBack logs are stored in:

~/.local/state/gitback/gitback.log

Logs use structured JSON and are useful when diagnosing synchronization or snapshot issues.

Before Opening an Issue

Collect:

gitback doctor
gitback health

and relevant log entries.

Include:

• GitBack version
• Operating system
• Error messages
• Reproduction steps

This significantly speeds up troubleshooting.

Next Step

Continue with:

• FAQ