14 KiB

Raw Blame History

Troubleshooting Guide

Common issues and their solutions for the Redmine-Gitea Sync Server.

422 Errors
Connection Issues
Sync Loop Issues
Performance Issues
PM2 Issues

Label and Field Mapping Issues

Issue: Priority/Tracker Not Syncing from Gitea to Redmine

Symptoms:

Gitea labels like "bug", "High Priority" not mapping to Redmine fields
All Redmine issues default to Bug/Normal priority

Cause: Gitea uses labels for everything, but Redmine has distinct tracker_id and priority_id fields.

Solution: The server now automatically maps labels back to Redmine fields:

Tracker Mapping:

bug label → Tracker ID 1 (Bug)
feature label → Tracker ID 2 (Feature)
support label → Tracker ID 3 (Support)

Priority Mapping:

Low Priority → Priority ID 1
Normal Priority → Priority ID 2
High Priority → Priority ID 3
Urgent → Priority ID 4
Immediate → Priority ID 5

Verification:

# Create issue in Gitea with labels "feature" and "High Priority"
# Check Redmine - should show as Feature with High priority

# Update to latest version
git pull
pm2 restart redmine-gitea-sync

Issue: Comments Not Syncing from Redmine to Gitea

Symptoms:

Add note/journal in Redmine
Comment doesn't appear in Gitea
Gitea → Redmine comments work fine

Causes:

Redmine webhook not configured for journal updates
Journal has no notes (only field changes)
Cache blocking the sync

Solutions:

Verify Redmine Webhook Events
- Go to: Administration → Settings → Repositories → Webhooks
- Ensure "Issues updated" is checked
- Redmine should send journals as part of issue updates

Check Logs

pm2 logs redmine-gitea-sync

# After adding a Redmine note, you should see:
# "Processing Redmine issue #X"
# "Synced Redmine journal #Y to Gitea comment on issue #Z"

Verify Journal Has Content
- Empty notes (only field changes) won't sync
- Add actual text to the note/journal

Check Journal Structure

# Enable debug logging
pm2 start ecosystem.config.cjs --env development

# Look for journal processing logs
pm2 logs redmine-gitea-sync | grep journal

Clear Cache

curl -X POST http://localhost:3002/cache/clear

Verification:

# 1. Add a note in Redmine with text content
# 2. Watch logs
pm2 logs redmine-gitea-sync

# Should see:
# [INFO] Processing Redmine issue #X
# [INFO] Updating existing Gitea issue #Y
# [INFO] Synced Redmine journal #Z to Gitea comment on issue #Y

# 3. Check Gitea issue - comment should appear with:
# [Redmine Journal #Z]
# **username** commented:
# 
# Your note text

422 Errors

Issue: "Request failed with status code 422" (Redmine → Gitea)

Symptoms:

[ERROR] Redmine to Gitea sync failed: Request failed with status code 422

Cause: Gitea API validation failure. The request payload contains invalid data.

Common Causes:

Invalid Label Format
- Labels must be set separately using label IDs, not in the issue creation payload
- Fixed in v2.0.0+
Invalid Date Format
- Gitea expects ISO 8601 format: 2025-12-17T00:00:00Z
- Fixed in v2.0.0+
Invalid Assignee
- Must be a valid Gitea username (string)
- User must exist in Gitea
Invalid Milestone
- Must be a valid milestone ID (number)
- Milestone must exist in the repository

Solutions:

Update to Latest Version

git pull
npm install
pm2 restart redmine-gitea-sync

Enable Verbose Logging

// In ecosystem.config.cjs
env: {
  LOG_LEVEL: 'debug',
  LOG_VERBOSE: 'true',
}

Restart and check logs:

pm2 restart redmine-gitea-sync --update-env
pm2 logs redmine-gitea-sync

Look for: Validation error details: {...}

Disable Problematic Features Temporarily

// In ecosystem.config.cjs
env: {
  SYNC_LABELS: 'false',
  SYNC_MILESTONES: 'false',
}

Verify Assignee Exists

# Test if user exists in Gitea
curl -H "Authorization: token YOUR_TOKEN" \
  https://gitea.example.com/api/v1/users/username

Check Date Formats
- Ensure Redmine due dates are valid
- Server will now auto-convert to ISO format

Verification:

# Watch logs in real-time
pm2 logs redmine-gitea-sync

# Create a test issue in Redmine
# Should see: "Successfully synced Redmine issue #X to Gitea issue #Y"

Issue: "Due date is not a valid date" (Gitea → Redmine)

Symptoms:

[ERROR] Gitea to Redmine sync failed: Request failed with status code 422
[ERROR] Validation error details: {"errors":["Due date is not a valid date"]}

Cause: Redmine expects dates in YYYY-MM-DD format (no time component), but Gitea sends ISO 8601 format with time.

Solution: This is automatically fixed in v2.0.0+. The server now:

Extracts only the date portion from ISO timestamps
Validates dates before sending to Redmine
Handles invalid date formats gracefully with warnings

Manual Fix:

git pull
pm2 restart redmine-gitea-sync

Verification:

# Create issue in Gitea with due date
# Watch logs - should see successful sync
pm2 logs redmine-gitea-sync

# Check Redmine - due date should appear correctly

Connection Issues

Issue: Cannot Connect to Redmine

Symptoms:

[ERROR] Redmine connection test failed

Solutions:

Verify API URL

# Test Redmine API
curl -H "X-Redmine-API-Key: YOUR_KEY" \
  https://redmine.example.com/issues.json

Check API Key
- Log into Redmine
- Go to: My Account → API access key
- Verify key matches REDMINE_API_KEY in config

Test Network Connectivity

# From server, test connection
telnet redmine.example.com 443
ping redmine.example.com

Check Firewall

# Ensure outbound HTTPS is allowed
sudo ufw status

Verify SSL Certificate

# Test SSL
openssl s_client -connect redmine.example.com:443

Issue: Cannot Connect to Gitea

Symptoms:

[ERROR] Gitea connection test failed

Solutions:

Verify API URL
- Should NOT include /api/v1
- Correct: https://gitea.example.com
- Incorrect: https://gitea.example.com/api/v1

Check Token

# Test Gitea API
curl -H "Authorization: token YOUR_TOKEN" \
  https://gitea.example.com/api/v1/user

Verify Token Permissions
- Token must have: repo, write:issue
- Regenerate token if needed

Check Owner Name

# Verify owner exists
curl -H "Authorization: token YOUR_TOKEN" \
  https://gitea.example.com/api/v1/users/YOUR_OWNER

Sync Loop Issues

Issue: Infinite Sync Loop

Symptoms:

Issues constantly updating
High CPU usage
Logs showing rapid back-and-forth updates

Cause: Cache not preventing loops properly.

Solutions:

Increase Cache TTL

// In ecosystem.config.cjs
env: {
  CACHE_TTL: '60000',  // 60 seconds
}

Clear Cache

curl -X POST http://localhost:3002/cache/clear

Verify Webhook Configuration
- Ensure webhooks are not triggering on every change
- Check webhook logs in Redmine/Gitea

Check for Multiple Instances

pm2 list
# Should show only one instance

Issue: Updates Not Syncing

Symptoms:

Changes made but not appearing on other platform
No errors in logs

Solutions:

Check Cache

# Cache might be blocking legitimate updates
curl -X POST http://localhost:3002/cache/clear

Verify Webhooks Are Firing

# Watch logs
pm2 logs redmine-gitea-sync

# Make a change in Redmine
# Should see: "Processing Redmine issue #X"

Test Webhooks Manually

# Test Redmine webhook
curl -X POST http://localhost:3002/webhook/redmine \
  -H "Content-Type: application/json" \
  -d @test-payload.json

# Test Gitea webhook
curl -X POST http://localhost:3002/webhook/gitea \
  -H "Content-Type: application/json" \
  -d @gitea-payload.json

Check Network Connectivity
- Ensure Redmine/Gitea can reach sync server
- Test from Redmine/Gitea servers:
```
curl http://sync-server:3002/health
```

Performance Issues

Issue: High Memory Usage

Symptoms:

pm2 list
# Shows high memory usage (>300MB)

Solutions:

Increase Memory Limit

// In ecosystem.config.cjs
max_memory_restart: '500M',

Check for Memory Leaks
```
pm2 monit
# Watch memory over time
```

Reduce Cache Size

env: {
  CACHE_TTL: '15000',  // Reduce to 15 seconds
}

Restart Regularly

// In ecosystem.config.cjs
cron_restart: '0 3 * * *',  // Daily at 3 AM

Issue: Slow Sync Performance

Symptoms:

Sync takes several seconds
Timeouts occurring

Solutions:

Increase Timeouts

env: {
  REDMINE_TIMEOUT: '60000',
  GITEA_TIMEOUT: '60000',
}

Reduce Retry Attempts

env: {
  RETRY_ATTEMPTS: '2',
  RETRY_DELAY: '500',
}

Check Network Latency

# Test latency
ping redmine.example.com
ping gitea.example.com

Disable Heavy Features

env: {
  SYNC_LABELS: 'false',
  SYNC_MILESTONES: 'false',
  SYNC_CUSTOM_FIELDS: 'false',
}

PM2 Issues

Issue: Process Keeps Restarting

Symptoms:

pm2 list
# Shows high restart count

Solutions:

Check Error Logs

pm2 logs redmine-gitea-sync --err --lines 50

Increase Restart Delay

// In ecosystem.config.cjs
restart_delay: 5000,
max_restarts: 5,

Verify Configuration

# Test configuration
node server.js
# Should start without errors

Issue: PM2 Not Starting on Boot

Symptoms:

Server boots but sync server not running

Solutions:

Regenerate Startup Script
```
pm2 unstartup
pm2 startup
pm2 save
```

Check Systemd Service

systemctl status pm2-yourusername
journalctl -u pm2-yourusername -n 50

Verify PM2 Save
```
pm2 save
ls ~/.pm2/dump.pm2
```

Issue: Logs Not Appearing

Symptoms:

pm2 logs redmine-gitea-sync
# Shows no output

Solutions:

Check Log Directory

ls -la ./logs/
# Should show error.log and out.log

Create Logs Directory

mkdir -p logs
chmod 755 logs
pm2 restart redmine-gitea-sync

Check Permissions

# Ensure PM2 user can write to logs
chown -R $USER:$USER logs/

Verify PM2 Config

// In ecosystem.config.cjs
error_file: './logs/error.log',
out_file: './logs/out.log',

Webhook Issues

Issue: Webhook Not Triggering

Symptoms:

No logs when creating/updating issues
Changes not syncing

Solutions:

Verify Webhook URL
- Redmine: http://your-server:3002/webhook/redmine
- Gitea: http://your-server:3002/webhook/gitea
Check Webhook Status
- In Gitea: Repository → Settings → Webhooks
- Look for delivery history and error messages

Test Webhook Delivery

# From Redmine/Gitea server
curl -X POST http://sync-server:3002/webhook/redmine \
  -H "Content-Type: application/json" \
  -d '{"payload":{"issue":{"id":1,"subject":"Test"}}}'

Check Firewall

# Ensure port 3002 is open
sudo ufw status
sudo ufw allow 3002/tcp

Use Reverse Proxy
- Configure Nginx to forward webhooks
- Use HTTPS for production

Project Mapping Issues

Issue: Project Not Found

Symptoms:

[WARN] No Gitea repo mapping found for Redmine project xyz
[ERROR] Redmine project xyz not found

Solutions:

Configure Project Mapping

// In ecosystem.config.cjs
env: {
  PROJECT_MAPPING: '{"GiteaRepo":"redmine-project-id"}',
}

Verify Project Identifiers

# Check Redmine project identifier
curl -H "X-Redmine-API-Key: KEY" \
  https://redmine.example.com/projects/PROJECT_ID.json

# Check Gitea repository name
curl -H "Authorization: token TOKEN" \
  https://gitea.example.com/api/v1/repos/OWNER/REPO

Use Automatic Mapping
- Leave PROJECT_MAPPING empty
- Server will auto-convert names

Debug Mode

Enable Maximum Verbosity

// In ecosystem.config.cjs
env: {
  NODE_ENV: 'development',
  LOG_LEVEL: 'debug',
  LOG_VERBOSE: 'true',
}

Restart:

pm2 restart redmine-gitea-sync --update-env

Or use development environment:

pm2 start ecosystem.config.cjs --env development

View Detailed Logs

# Real-time logs with timestamps
pm2 logs redmine-gitea-sync --timestamp

# Last 200 lines
pm2 logs redmine-gitea-sync --lines 200

# Only errors
pm2 logs redmine-gitea-sync --err

# Follow and filter
pm2 logs redmine-gitea-sync | grep ERROR

Getting Help

Collect Debug Information

# 1. Check server status
curl http://localhost:3002/status

# 2. Collect logs
pm2 logs redmine-gitea-sync --lines 100 > debug.log

# 3. Check configuration
pm2 show redmine-gitea-sync

# 4. Test connectivity
curl -H "X-Redmine-API-Key: KEY" https://redmine.example.com/issues.json
curl -H "Authorization: token TOKEN" https://gitea.example.com/api/v1/user

# 5. Check process status
pm2 list
pm2 monit

Report an Issue

When reporting issues, include:

Server status output
Relevant logs (last 50-100 lines)
Configuration (with sensitive data removed)
Steps to reproduce
Expected vs actual behavior

Additional Resources

README.md - Full documentation
PM2_GUIDE.md - PM2 management
API_DOCUMENTATION.md - API reference
DEPLOYMENT.md - Deployment guide

14 KiB Raw Blame History

Troubleshooting Guide

Table of Contents

Label and Field Mapping Issues

Issue: Priority/Tracker Not Syncing from Gitea to Redmine

Issue: Comments Not Syncing from Redmine to Gitea

422 Errors

Issue: "Request failed with status code 422" (Redmine → Gitea)

Issue: "Due date is not a valid date" (Gitea → Redmine)

Connection Issues

Issue: Cannot Connect to Redmine

Issue: Cannot Connect to Gitea

Sync Loop Issues

Issue: Infinite Sync Loop

Issue: Updates Not Syncing

Performance Issues

Issue: High Memory Usage

Issue: Slow Sync Performance

PM2 Issues

Issue: Process Keeps Restarting

Issue: PM2 Not Starting on Boot

Issue: Logs Not Appearing

Webhook Issues

Issue: Webhook Not Triggering

Project Mapping Issues

Issue: Project Not Found

Debug Mode

Enable Maximum Verbosity

View Detailed Logs

Getting Help

Collect Debug Information

Report an Issue

Additional Resources

14 KiB

Raw Blame History