home Explore Documentation & Help
Register Sign In

Navigation

Getting Started

User Guide

Team Collaboration

Advanced

FAQ & Help

Troubleshooting

Common Issues

Installation Problems

Port Already in Use

Error: listen tcp :3000: bind: address already in use

Solution:

# Find process using port 3000
lsof -i :3000  # Linux/macOS
netstat -ano | findstr :3000  # Windows

# Kill process
kill -9 <PID>  # Linux/macOS
taskkill /PID <PID> /F  # Windows

# Or use different port
./gityar web -p 3001

Database Connection Failed

Error: Failed to connect to database

Solutions:

SQLite:

# Check write permissions
chmod 755 data/

MySQL:

[database]
DB_TYPE = mysql
HOST = 127.0.0.1:3306
NAME = gityar
USER = gityar
PASSWD = correct_password
  • Verify MySQL is running
  • Check credentials
  • Ensure database exists
  • Check user permissions

PostgreSQL:

[database]
DB_TYPE = postgres
HOST = 127.0.0.1:5432
NAME = gityar
USER = gityar
PASSWD = correct_password
SSL_MODE = disable
  • Verify PostgreSQL is running
  • Check credentials
  • Ensure database exists

Authentication Issues

Can't Login

Possible causes:

  1. Wrong credentials: Reset password
  2. Account not activated: Check email for activation link
  3. Account disabled: Contact admin

Reset Password:

  1. Click "Forgot password" on login page
  2. Enter email
  3. Follow reset link
  4. Set new password

LDAP Authentication Failed

Solutions:

  • Verify LDAP server is reachable
  • Check bind DN and password
  • Verify user search base
  • Check logs for LDAP errors

In app.ini:

[auth]
ENABLE_LDAP = true

[ldap]
HOST = ldap.example.com:389
BASE_DN = dc=example,dc=com

Repository Issues

Can't Push to Repository

Error: Permission denied

Solutions:

  1. Check repository access:

    • Are you a collaborator?
    • Do you have write access?
    • Are you in the correct team?

  2. Check authentication:

    # Test SSH
ssh -T git@localhost
   
# Test HTTP
curl -u username:password http://localhost:3000/user/repo.git/info/refs

  3. Check branch protection:

    • Is the branch protected?
    • Do you have permission to push?

Git Clone Fails

HTTP:

# Check URL
git clone http://localhost:3000/user/repo.git

# With credentials
git clone http://username:password@localhost:3000/user/repo.git

SSH:

# Check SSH key
ssh -T git@localhost

# Verbose
GIT_SSH_COMMAND="ssh -v" git clone git@localhost:user/repo.git

Repository Shows Empty

Causes:

  1. No commits pushed yet
  2. Wrong branch selected
  3. Repository not initialized

Solution:

cd your-repo
git status
git log --all
git branch -a

# If empty, create initial commit
echo "# My Project" > README.md
git add .
git commit -m "Initial commit"
git push origin main

Performance Issues

Slow Page Loads

Solutions:

  1. Enable caching:

    [cache]
ADAPTER = memory
INTERVAL = 60

  2. Use reverse proxy:

    • Nginx or Apache
    • Enable gzip compression

  3. Optimize database:

    # MySQL
mysqlcheck -o gityar -u root -p
   
# PostgreSQL
vacuumdb -d gityar

  4. Increase resources:

    • More RAM
    • Faster CPU
    • SSD storage

Large Repository Slow

Solutions:

  1. Enable Git garbage collection:

    [repository]
ENABLE_AUTO_GIT_GC = true
GC_AUTO_THRESHOLD = 100

  2. Use shallow clone:

    git clone --depth 50 http://localhost:3000/user/repo.git

  3. Enable LFS for large files

Email Issues

Emails Not Sending

Check configuration:

[mailer]
ENABLED = true
HOST = smtp.example.com:587
FROM = gityar@example.com
USER = gityar@example.com
PASSWD = password
IS_TLS_ENABLED = true

Test connection:

telnet smtp.example.com 587

Check logs:

tail -f log/gityar.log | grep mailer

Webhook Issues

Webhooks Not Firing

Checklist:

  • Webhook is active
  • URL is accessible
  • Events are configured
  • No firewall blocking
  • SSL certificate valid

Test webhook:

  1. Go to webhook settings
  2. Click "Test Delivery"
  3. Check response

Check logs:

tail -f log/gityar.log | grep webhook

Log Files

Location

log/gityar.log
log/http.log

Log Levels

In app.ini:

[log]
MODE = file
LEVEL = Info  # Trace, Debug, Info, Warn, Error, Critical

Enable Debug Logging

[log]
LEVEL = Debug

Restart gityar and check logs for detailed information.

Database Issues

Backup and Restore

Backup:

# SQLite
cp data/gityar.db gityar-backup.db

# MySQL
mysqldump -u root -p gityar > backup.sql

# PostgreSQL
pg_dump gityar > backup.sql

Restore:

# SQLite
cp gityar-backup.db data/gityar.db

# MySQL
mysql -u root -p gityar < backup.sql

# PostgreSQL
psql gityar < backup.sql

Database Migration

SQLite to MySQL:

  1. Export from SQLite
  2. Create MySQL database
  3. Import data
  4. Update app.ini
  5. Restart gityar

Common Error Messages

"Template Not Found"

Solution:

# Check templates directory
ls templates/

# Rebuild from source
go build -o gityar ./cmd/gityar

"Static File Not Found"

Solution:

# Check public directory
ls public/

# Rebuild or restart
./gityar web

"Session Expired"

Solution:

  • Clear browser cache
  • Check session configuration
  • Restart gityar

Getting Help

Resources

When Reporting Issues

Include:

  1. gityar version
  2. Operating system
  3. Database type and version
  4. Error messages
  5. Steps to reproduce
  6. Log files (if relevant)

Preventive Measures

Regular Maintenance

  • ✅ Backup database regularly
  • ✅ Monitor disk space
  • ✅ Update gityar to latest version
  • ✅ Review logs periodically
  • ✅ Clean up old repositories
  • ✅ Monitor performance metrics

Security Best Practices

  • ✅ Keep gityar updated
  • ✅ Use strong passwords
  • ✅ Enable 2FA
  • ✅ Regular security audits
  • ✅ Monitor access logs
  • ✅ Backup regularly

Next Steps