Troubleshooting Guide

Find solutions to common issues you might encounter while using GitProductivity.

Connection Issues

GitHub Connection Failed

Symptoms: Unable to connect GitHub account or repositories not appearing.

Solutions:

1. Check permissions: Ensure you have admin/maintain access to repositories
2. Re-authorize: Disconnect and reconnect your GitHub account
3. Check GitHub status: Verify GitHub is operational
4. Browser issues: Try a different browser or clear cache

GitLab Connection Issues

Symptoms: Cannot connect to GitLab or repositories not syncing.

Solutions:

1. Verify instance URL: Ensure correct GitLab URL (cloud or self-hosted)
2. Check access token: Verify token has required scopes (read_api, read_repository)
3. Test API access: Use the GitLab API directly to verify connectivity
4. Firewall rules: Ensure GitLab instance is accessible from our servers

Repository Not Syncing

Symptoms: Connected repository shows no data or stale data.

Solutions:

1. Check sync status: Look for last sync timestamp in dashboard
2. Manual refresh: Click "Refresh" on the repository
3. Verify commits: Ensure repository has commit history
4. Check exclusions: Review any configured commit exclusions

Data Issues

Missing Developer Data

Symptoms: Developer appears in Git commits but not in analytics.

Solutions:

1. Email matching: Ensure Git commit email matches team member email
2. Check attribution: Review how commits are being attributed
3. Invite to team: Developer must be added to your GitProductivity team
4. Refresh data: Trigger a manual sync

Incorrect Workday Estimates

Symptoms: Workday estimates seem too high or too low.

Solutions:

1. Review exclusions: Check for excluded commits (merge, automated)
2. Consider context: Large refactors may show as lower productivity
3. Time range: Verify correct date range is selected
4. Compare trends: Look at trends over time rather than absolute numbers

Data Not Updating

Symptoms: Dashboard shows old data despite new commits.

Solutions:

1. Sync frequency: Check sync schedule in settings
2. Manual sync: Trigger a manual repository sync
3. Check webhook status: Verify webhooks are working (if applicable)
4. API rate limits: Ensure not hitting rate limits

Authentication Issues

Can't Log In

Symptoms: Unable to access account.

Solutions:

1. Password reset: Use "Forgot Password" to reset
2. OAuth issues: Try signing in with different provider
3. Browser issues: Clear cookies and try incognito mode
4. Account exists: Verify account was created (check email)

API Key Not Working

Symptoms: API requests return 401 errors.

Solutions:

1. Check key format: Ensure correct format (gp_live_...)
2. Verify permissions: API key may lack required scopes
3. Key not expired: Check key expiration in settings
4. Generate new key: Create a new API key if needed

Performance Issues

Slow Dashboard

Symptoms: Dashboard loads slowly or times out.

Solutions:

1. Large data sets: Try filtering by date range
2. Browser cache: Clear browser cache
3. Network issues: Check internet connection
4. Browser extension: Try disabling extensions

Export Failing

Symptoms: Cannot export data or export times out.

Solutions:

1. Reduce scope: Export smaller date ranges
2. File format: Try different export format
3. Peak hours: Try during off-peak hours
4. Contact support: For large exports, contact support

Self-Hosted Issues

Docker Container Won't Start

Symptoms: Container fails to start or exits immediately.

Solutions:

1. Check logs: Run docker-compose logs app
2. Port conflicts: Ensure port 3000 is available
3. Environment variables: Verify all required vars are set
4. Resource limits: Ensure sufficient CPU/memory available

Database Connection Failed

Symptoms: App can't connect to database.

Solutions:

1. Check DATABASE_URL: Verify connection string format
2. Database running: Ensure PostgreSQL container is running
3. Network: Verify containers can communicate
4. Credentials: Check username/password in connection string

Getting More Help

If you're still experiencing issues:

1. Search docs: Check our FAQ for more answers
2. Contact support: Email support@gitproductivity.com
3. Include details: Provide:
   • Account email
   • Steps to reproduce
   • Error messages
   • Screenshots if relevant