FAQ

MirthSync FAQ - Troubleshooting & Common Questions

Common questions and solutions for MirthSync CLI and Plugin. If you don’t find your question here, please ask in GitHub Discussions or report an issue.

General Questions

Which versions of Mirth Connect does MirthSync support?

MirthSync is compatible with:

• Open-source Mirth Connect 4.x ✅
• Open Integration Engine (OIE) ✅ (all versions)

Compatibility not guaranteed:

• NextGen’s paid/commercial Mirth Connect versions

Commercial Versions

We do not have information about compatibility with NextGen’s paid/commercial Mirth Connect versions going forward, as we do not have access to test against those versions. If you’re using a commercial version, we recommend testing MirthSync in a non-production environment first.

What happened to open-source Mirth Connect? Should I use OIE instead?

NextGen Healthcare has discontinued open-source development of Mirth Connect and now only offers commercial/paid versions.

Open Integration Engine (OIE) is the community-driven open-source fork that continues development of the integration engine. OIE provides:

• Continued open-source development - Active community development and contributions
• Security patches and updates - Regular updates and bug fixes
• Community support - Active community forums and discussion channels
• API compatibility - Maintains compatibility with Mirth Connect APIs

MirthSync fully supports both:

• Legacy open-source Mirth Connect 4.x
• Open Integration Engine (OIE) - all versions

Migration recommendation: If you’re currently using open-source Mirth Connect, you should consider migrating to OIE for continued updates, security patches, and community support.

OIE Migration

OIE maintains API compatibility with open-source Mirth Connect, so MirthSync works identically with both platforms. You can use the same MirthSync configurations and workflows whether you’re on open-source Mirth Connect or OIE.

Learn more:

• Open Integration Engine - Official OIE repository
• OIE Documentation - User guides and documentation

Does MirthSync work with Open Integration Engine (OIE)?

Yes! MirthSync works with both open-source Mirth Connect and Open Integration Engine (OIE).

Since OIE is a fork of open-source Mirth Connect, MirthSync can manage channels and configurations for both platforms using the same API-based approach. Simply point your MIRTH_URL to your OIE server’s API endpoint.

Both the CLI and Plugin are fully compatible with OIE.

Does MirthSync require Git to be installed separately?

No! MirthSync CLI includes an embedded Git binary, so you don’t need to install Git separately.

The Plugin also includes embedded Git. Everything you need is bundled—no separate Git installation required.

Is MirthSync free? Are there any costs?

Yes, MirthSync is completely free - both the CLI and Admin Console Plugin.

MirthSync CLI:

• ✅ Free and open-source - MIT license
• ✅ Commercial use allowed - Use in commercial environments freely
• ✅ Modify and distribute - Full source code available on GitHub
• ✅ No vendor lock-in - Fork and customize as needed

MirthSync Admin Console Plugin:

• ✅ Free to use - No cost, no subscription fees
• ⚠️ Not open-source - Proprietary software (closed source)
• ✅ Free forever - No plans to charge for the plugin
• ℹ️ Why not open source? - The plugin integrates with proprietary Mirth Connect Admin Console APIs and contains implementation details we don’t publicly disclose

Both are free, key difference:

• CLI - Open source, can modify and redistribute
• Plugin - Proprietary, can use freely but source code not available

No hidden costs:

• ❌ No subscription fees or premium tiers
• ❌ No feature restrictions or paywalls
• ❌ No usage limits or license costs

Potential costs (infrastructure only):

• Git hosting - GitHub, GitLab, Bitbucket offer free tiers (optional)
• Infrastructure - Your existing Mirth Connect server costs (not MirthSync-specific)

Download:

• CLI - GitHub - Open source (clone or download JAR)
• Releases - Download JAR releases
• Plugin - Releases - Free download

Why should I use version control for Mirth Connect?

Version control for Mirth Connect provides critical benefits for compliance, safety, and collaboration:

Compliance & Audit:

• 📋 Audit trail - Track who changed what and when (HIPAA, SOC 2, FDA 21 CFR Part 11)
• 📊 Change documentation - Complete history of all configuration changes
• ✅ Regulatory compliance - Meet auditing and traceability requirements

Safety & Recovery:

• ⏮️ Instant rollback - Revert bad changes to any previous state in seconds
• 💾 Disaster recovery - Complete backup with point-in-time restore capability
• 🔒 Configuration backup - Never lose channel configurations

Team Collaboration:

• 👥 Multi-developer - Multiple team members work simultaneously without conflicts
• 🔍 Peer review - Review and approve changes before production
• 💬 Change context - Commit messages explain why changes were made

Deployment Management:

• 🎯 Environment consistency - Deploy exact same configurations across dev/staging/production
• 🏷️ Release management - Tag stable releases (v1.0, v2.0) and deploy specific versions
• ⚖️ Configuration drift prevention - Detect and prevent environment inconsistencies

Without version control, you risk:

• ❌ Data loss from accidental channel deletion
• ❌ Compliance violations and failed audits
• ❌ Production deployment errors
• ❌ Inability to rollback problematic changes
• ❌ Team collaboration conflicts

Can MirthSync version control code templates and global scripts?

Yes! MirthSync manages all Mirth Connect configuration, not just channels:

What’s included:

1. Channels - All channel configurations, transformers, filters, and connectors
2. Code Templates - Reusable JavaScript code libraries and functions
3. Global Scripts - Deploy, undeploy, preprocessor, and postprocessor scripts
4. Configuration Map - Global variables and settings
5. Server Settings - Subset of server configuration

File structure:

mirthsync-repo/
├── channels/
│   ├── HL7_ADT_Processor.channel
│   └── FHIR_Patient_Import.channel
├── codeTemplates/
│   ├── DateUtils.xml
│   └── PatientLookup.xml
├── globalScripts/
│   ├── deploy.js
│   └── undeploy.js
└── configurationMap.properties

Benefits:

• ✅ Complete configuration as code - Entire Mirth instance in Git
• ✅ IDE editing - Edit all code in VS Code with syntax highlighting
• ✅ Versioned together - Channels and dependent code templates deployed as a unit
• ✅ Cross-environment deployment - Deploy complete stack to any environment

How do I migrate from manual Mirth Connect management to MirthSync?

Migration is straightforward and risk-free - your existing Mirth Connect setup remains unchanged:

Migration steps:

1. Install MirthSync (requires Java 8+)

   # Clone from GitHub
   git clone https://github.com/SagaHealthcareIT/mirthsync.git
   cd mirthsync
   
   # Or download a release
   curl -L -o mirthsync.zip https://github.com/SagaHealthcareIT/mirthsync/releases/download/v3.5.0/mirthsync-3.5.0.zip
   unzip mirthsync.zip

   Or download the Admin Console Plugin

2. Create target directory and initialize Git

   mkdir mirth-config
   cd mirth-config
   git init
   cd ..

3. Set password environment variable (the only supported env var)

   export MIRTHSYNC_PASSWORD="your-password"

4. Extract current configuration (creates baseline)

   ./mirthsync.sh -s https://mirth.example.com:8443/api -u admin -t ./mirth-config pull

5. Commit to Git (use native git for remote operations)

   ./mirthsync.sh -t ./mirth-config git add
   ./mirthsync.sh -t ./mirth-config --commit-message "Initial Mirth Connect configuration baseline" git commit

6. Push to remote (use native git - mirthsync doesn’t support remote add)

   cd mirth-config
   git remote add origin https://github.com/yourorg/mirth-config.git
   git push -u origin main
   cd ..

7. Start using MirthSync workflow

   • Edit channels in IDE or Admin Console
   • Run ./mirthsync.sh -s server -u admin -t ./mirth-config pull to sync changes to files
   • Commit changes to Git
   • Run ./mirthsync.sh -s server -u admin -t ./mirth-config push to deploy

Transition period:

• ✅ Run both workflows - Use Admin Console and MirthSync simultaneously during transition
• ✅ No server changes - MirthSync reads via API, doesn’t modify Mirth until explicit push
• ✅ Gradual adoption - Team can adopt at their own pace

Risk-free:

Your existing Mirth Connect server and Admin Console workflows continue working normally. MirthSync is additive - it doesn’t replace or break existing processes.

CLI vs Plugin: Which should I use?

Use CLI When	Use Plugin When
Automating with scripts Working in terminal CI/CD pipelines Scripting deployments Prefer command-line workflow	Working in Admin Console Prefer visual interface Want preset management Need output window Team uses Admin Console exclusively

Can I use both? Yes! The CLI and Plugin work with the same file format and can be used together.

Can I use MirthSync with GitHub Actions for CI/CD?

Absolutely! MirthSync is designed for CI/CD automation.

You can use it in:

• GitHub Actions
• GitLab CI
• Jenkins
• Any CI/CD platform

Setup:

1. MirthSync is a Java application - set up Java 8+ in your CI/CD environment
2. Download the MirthSync JAR from GitHub releases
3. Store MIRTHSYNC_PASSWORD as a secret (the only supported env var)
4. Pass server URL and username via command-line flags (-s and -u)
5. Run ./mirthsync.sh -s server -u admin -t ./config pull to extract configurations
6. Run ./mirthsync.sh -s server -u admin -t ./config push to deploy

See the CI/CD Setup Guide for detailed examples.

Connection & Authentication

How do I troubleshoot connection errors?

Use this flowchart to quickly identify your connection issue:

“Connection refused” or “ECONNREFUSED”

Symptoms:

Error: connect ECONNREFUSED 127.0.0.1:8443
Unable to connect to Mirth Connect server

Solutions:

1. Verify Mirth Connect is running

   systemctl status mirthconnect
   # or
   ps aux | grep mirth

2. Check the URL includes /api

   # Wrong
   ./mirthsync.sh -s https://mirth.example.com:8443 ...
   
   # Correct
   ./mirthsync.sh -s https://mirth.example.com:8443/api ...

3. Verify firewall allows connection

   telnet mirth.example.com 8443
   # or
   nc -zv mirth.example.com 8443

”Authentication failed” or “401 Unauthorized”

Symptoms:

Error: Authentication failed
401 Unauthorized
Invalid username or password

Solutions:

1. Verify credentials

   # Test credentials with curl
   curl -u admin:admin https://mirth.example.com:8443/api/system/info

2. Check MIRTHSYNC_PASSWORD environment variable (only supported env var)

   env | grep MIRTHSYNC

3. Verify user has API access

   • Log into Mirth Connect Administrator
   • Go to Settings → Users
   • Verify user has “REST API” permission

4. Check for special characters in password

   # Use single quotes to prevent shell expansion
   export MIRTHSYNC_PASSWORD='p@ssw0rd!#'

SSL Certificate Errors

Symptoms:

Error: unable to verify the first certificate
UNABLE_TO_VERIFY_LEAF_SIGNATURE

Solutions:

Self-Signed Certificate

Add CA Certificate (Recommended)

{
  "security": {
    "tls": {
      "enabled": true,
      "verify": true,
      "ca": "/path/to/company-ca.crt"
    }
  }
}

Disable Verification (Dev Only)

{
  "security": {
    "tls": {
      "enabled": true,
      "verify": false
    }
  }
}

Expired Certificate

# Check certificate expiration
openssl s_client -connect mirth.example.com:8443 < /dev/null 2>/dev/null | openssl x509 -noout -dates

# Renew certificate in Mirth Connect configuration

“Timeout” or “ETIMEDOUT”

Symptoms:

Error: Request timeout after 30000ms

Solutions:

1. Increase timeout

   {
     "server": {
       "timeout": 60000 // 60 seconds
     }
   }

2. Or use environment variable

   export MIRTH_TIMEOUT=60000

3. Check network latency

   ping mirth.example.com

Git Operations

”Not a git repository”

Symptoms:

fatal: not a git repository (or any of the parent directories): .git

Solutions:

# Initialize git repository in target directory
cd mirth-config
git init
cd ..

# Add .gitignore
cat > mirth-config/.gitignore << EOF
.env
*.log
mirthsync.local.json
EOF

# Make initial commit using MirthSync git commands
./mirthsync.sh -t ./mirth-config git add
./mirthsync.sh -t ./mirth-config --commit-message "Initial commit" git commit

Merge Conflicts

Symptoms:

CONFLICT (content): Merge conflict in channels/ADT_Inbound/channel.xml

Solutions:

1. View conflicts

   ./mirthsync.sh -t ./mirth-config git status
   ./mirthsync.sh -t ./mirth-config git diff

2. Resolve manually

   # Open file and look for conflict markers:
   # <<<<<<< HEAD
   # Your changes
   # =======
   # Their changes
   # >>>>>>> branch
   
   # Edit file to resolve
   nano mirth-config/channels/ADT_Inbound/channel.xml
   
   # Mark as resolved
   ./mirthsync.sh -t ./mirth-config git add
   ./mirthsync.sh -t ./mirth-config --commit-message "Resolve merge conflict" git commit

3. Use theirs or ours (use native git - checkout with flags not supported in mirthsync)

   cd mirth-config
   
   # Keep remote version
   git checkout --theirs channels/ADT_Inbound/channel.xml
   
   # Keep local version
   git checkout --ours channels/ADT_Inbound/channel.xml
   
   cd ..
   ./mirthsync.sh -t ./mirth-config git add

In the Plugin:

• Click “Resolve Conflict” button
• Choose: Keep Local, Accept Remote, or Manual Edit

”Push rejected” errors

Symptoms:

error: failed to push some refs
hint: Updates were rejected because the remote contains work you don't have

Solutions:

1. Pull before push (this refers to git pull from remote, not mirthsync pull from Mirth server)

   # Pull remote git changes
   ./mirthsync.sh -t ./mirth-config git pull
   
   # Resolve any conflicts
   
   # Then push to remote
   ./mirthsync.sh -t ./mirth-config git push

2. Force push (use native git - force flag not supported in mirthsync)

   # Only if you're SURE you want to overwrite remote
   cd mirth-config && git push --force origin main && cd ..

Force Push Warning

Force pushing overwrites remote history. Only use if you’re certain no one else has pulled the remote changes.

Authentication failed on push/pull

For HTTPS: (use native git - remote set-url not supported in mirthsync)

# Use Personal Access Token as password
# GitHub: Settings → Developer settings → Personal access tokens
# Create token with 'repo' scope

# Set remote URL with token (use native git)
cd mirth-config
git remote set-url origin https://USERNAME:TOKEN@github.com/yourorg/repo.git
cd ..

# Or use credential helper (use native git)
git config --global credential.helper store

For SSH: (use native git)

# Generate SSH key
ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

# Add public key to GitHub
cat ~/.ssh/id_rsa.pub
# Copy output → GitHub Settings → SSH Keys

# Change remote to SSH (use native git)
cd mirth-config
git remote set-url origin git@github.com:yourorg/repo.git
cd ..

# Test connection
ssh -T git@github.com

IDE Integration

Do I need to learn command line to use MirthSync with an IDE?

No! Most IDEs have built-in Git GUIs. You can use visual buttons for commits, pushes, and pulls.

Modern IDEs like VS Code, IntelliJ IDEA, and Sublime Text provide:

• Visual Git panels for staging and committing changes
• Point-and-click buttons for push/pull operations
• Diff viewers for reviewing changes
• Branch management through GUI
• Merge conflict resolution tools

You can use MirthSync with an IDE entirely through visual interfaces—no command line required.

Can I still use the Mirth Connect Admin Console?

Absolutely! Use the Admin Console for deployment and monitoring, and your IDE for editing. MirthSync syncs between them.

Recommended workflow:

1. Edit in IDE - Use your favorite IDE for editing channel configurations, transformers, and code templates
2. Use MirthSync - Pull/push configurations between IDE and Mirth Connect
3. Monitor in Admin Console - Use Admin Console for channel status, message viewer, and troubleshooting

This gives you the best of both worlds: powerful editing tools and real-time monitoring.

What if my team doesn’t want to use IDEs?

That’s fine! Use the MirthSync Plugin for a GUI in the Admin Console. Team members can choose their preferred tools.

Mix and match approaches:

• Some team members use the CLI for automation
• Others use the Plugin for visual workflows
• Some prefer IDEs for advanced editing
• All work with the same file format and repository

Everyone can contribute using their preferred tools while maintaining a single source of truth in version control.

Will this work with my existing Mirth Connect setup?

Yes! MirthSync works with any open-source Mirth Connect 3.x/4.x or Open Integration Engine installation.

Compatible with:

• Open-source Mirth Connect 3.x and 4.x ✅
• Open Integration Engine (OIE) - all versions ✅
• Any platform: Linux, Windows, macOS

No changes to your Mirth Connect setup required—MirthSync uses the standard REST API.

Which IDE should I choose?

VS Code is the most popular choice for its balance of features and ease of use. If you’re already familiar with another editor, use that—MirthSync works with any text editor.

Popular choices:

Visual Studio Code (Recommended for most users)

• Free and cross-platform
• Excellent extensions marketplace
• Built-in Git integration
• Great XML and JavaScript support

IntelliJ IDEA / WebStorm

• Powerful refactoring and debugging
• Superior code analysis
• Great for Java developers

Sublime Text

• Lightweight and fast
• Great for large files
• Powerful search capabilities

Vim / Neovim

• Terminal-based
• Highly customizable
• Perfect for remote work via SSH

See the IDE Setup Guide for detailed configuration instructions.

Performance Issues

Slow pull/push operations

Solutions:

1. Increase timeout

   {
     "server": {
       "timeout": 120000 // 2 minutes
     }
   }

2. Sync only what you need

   {
     "sync": {
       "channels": true,
       "codeTemplates": true,
       "globalScripts": false,
       "libraries": false
     }
   }

3. Use filtering

   # Pull only specific channels
   mirthsync pull --channels "ADT_*,Lab_*"

Plugin UI is slow or unresponsive

Solutions:

1. Check repository size

   du -sh /var/lib/mirthconnect/repository
   # If >500MB, clean up old backups

2. Increase timeout in plugin settings

   • Plugin Settings → Operation Timeout
   • Increase to 60s or 120s

3. Disable auto-refresh

   • Plugin Settings → Auto-refresh Status
   • Disable or increase interval to 60 seconds

Debug Mode

How do I enable debug logging?

Enable verbose logging for troubleshooting:

CLI:

# Verbose output
mirthsync pull --verbose

# Debug output (very detailed)
export DEBUG=mirthsync:*
mirthsync pull

# Log to file
mirthsync pull --verbose 2>&1 | tee mirthsync.log

Plugin:

1. Plugin Settings → Advanced → Enable Debug Logging
2. View logs:

   tail -f /opt/mirthconnect/logs/mirth.log | grep -i mirthsync

Deployment & Multi-Environment

How do I manage multiple Mirth Connect environments (dev/staging/prod)?

MirthSync supports multi-environment workflows through environment-specific configuration:

Approach 1: Separate Branches

# Branch per environment
main          → production
staging       → staging environment
dev           → development environment

# Workflow - switch branch with mirthsync
./mirthsync.sh -t ./mirth-config git checkout dev
# Make changes
./mirthsync.sh -t ./mirth-config git add
./mirthsync.sh -t ./mirth-config --commit-message "Changes" git commit
./mirthsync.sh -t ./mirth-config git push

# Promote to staging (use native git for merge - not supported in mirthsync)
./mirthsync.sh -t ./mirth-config git checkout staging
cd mirth-config && git merge dev && cd ..
./mirthsync.sh -s https://staging-server:8443/api -u admin -t ./mirth-config push

# Promote to production (use native git for merge)
./mirthsync.sh -t ./mirth-config git checkout main
cd mirth-config && git merge staging && cd ..
./mirthsync.sh -s https://prod-server:8443/api -u admin -t ./mirth-config push

Approach 2: Use Different Server Flags

# Pull from dev
./mirthsync.sh -s https://dev-mirth.example.com:8443/api -u admin -t ./mirth-config pull

# Push to staging
./mirthsync.sh -s https://staging-mirth.example.com:8443/api -u admin -t ./mirth-config push

# Push to production
./mirthsync.sh -s https://prod-mirth.example.com:8443/api -u admin -t ./mirth-config push

Approach 3: Shell Scripts for Each Environment

deploy-dev.sh

#!/bin/bash
export MIRTHSYNC_PASSWORD="dev-password"
./mirthsync.sh -s https://dev-mirth:8443/api -u admin -t ./mirth-config "$@"

# deploy-prod.sh
#!/bin/bash
export MIRTHSYNC_PASSWORD="prod-password"
./mirthsync.sh -s https://prod-mirth:8443/api -u admin -t ./mirth-config "$@"

# Usage:
./deploy-dev.sh pull
./deploy-prod.sh push

Best Practices:

• ✅ Develop in dev - Make all changes in development environment first
• ✅ Test in staging - Promote to staging for integration testing
• ✅ Deploy to production - Only deploy after staging approval
• ✅ Use Git tags - Mark production releases (v1.0.0, v1.1.0)
• ✅ Prevent drift - Deploy same files to all environments

Benefits:

• 🎯 Environment consistency - Same configuration across all environments
• 🔒 Controlled promotion - Structured workflow prevents accidental production changes
• 📊 Audit trail - Git history shows what was deployed when and where
• ⏮️ Easy rollback - Revert any environment to any previous state

How do I promote Mirth Connect channels between servers?

Channel promotion moves configurations from one server to another (dev → staging → production):

Pull from Source, Push to Target

# Step 1: Set password (only supported env var)
export MIRTHSYNC_PASSWORD="dev-password"

# Step 2: Pull from source environment (dev)
./mirthsync.sh -s https://dev-mirth.example.com:8443/api -u admin -t ./mirth-config pull

# Step 3: Commit changes
./mirthsync.sh -t ./mirth-config git add
./mirthsync.sh -t ./mirth-config --commit-message "Updated channels from dev" git commit

# Step 4: Push to target environment (prod)
export MIRTHSYNC_PASSWORD="prod-password"
./mirthsync.sh -s https://prod-mirth.example.com:8443/api -u admin -t ./mirth-config push

Shell Script Wrapper

# Pull from dev
export MIRTHSYNC_PASSWORD="dev-pass"
./mirthsync.sh -s https://dev-mirth:8443/api -u admin -t ./mirth-config pull

./mirthsync.sh -t ./mirth-config git add
./mirthsync.sh -t ./mirth-config --commit-message "Sync from dev" git commit

# Push to prod
export MIRTHSYNC_PASSWORD="prod-pass"
./mirthsync.sh -s https://prod-mirth:8443/api -u admin -t ./mirth-config push

CI/CD Automation

# GitHub Actions example
name: Promote to Production
on:
  push:
    branches: [main]
env:
  MIRTHSYNC_VERSION: "3.5.0"
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-java@v3
        with:
          distribution: "temurin"
          java-version: "11"
      - name: Download MirthSync
        run: |
          curl -L -o mirthsync.zip https://github.com/SagaHealthcareIT/mirthsync/releases/download/v${MIRTHSYNC_VERSION}/mirthsync-${MIRTHSYNC_VERSION}.zip
          unzip mirthsync.zip
          chmod +x mirthsync-${MIRTHSYNC_VERSION}/mirthsync.sh
      - name: Deploy to Production
        env:
          MIRTHSYNC_PASSWORD: ${{ secrets.PROD_MIRTHSYNC_PASSWORD }}
        run: ./mirthsync-${MIRTHSYNC_VERSION}/mirthsync.sh -s ${{ secrets.PROD_MIRTH_SERVER }} -u ${{ secrets.PROD_MIRTH_USERNAME }} -t . push

Safety Checks:

1. Review before promotion

   # See what will be deployed
   mirthsync git diff production..staging

2. Test in staging first

   • Always promote dev → staging → production
   • Never skip staging environment

3. Use pull requests

   • Require code review before merging
   • Automated tests run before deployment

4. Backup before promotion

   # Backup production before deploying
   ./mirthsync.sh -s https://prod-mirth:8443/api -u admin -t ./backup pull
   # Use native git for tagging (mirthsync doesn't support git tag)
   cd backup && git tag backup-$(date +%Y%m%d-%H%M%S) && cd ..

Benefits:

• ✅ Exact configurations - Same files deployed to all servers
• ✅ No manual copy - Automated promotion reduces human error
• ✅ Audit trail - Git log shows all promotions
• ✅ Easy rollback - Revert to previous version if issues occur