Search docs.molo17.com
    A newer version of this documentation is available.
    View Latest (v2.3)

    Troubleshooting guide

    This guide provides instructions for troubleshooting Gluesync issues. Whether you’re a user checking notifications or a system administrator collecting logs, you’ll find the relevant information below.

    Common mistakes and solutions

    Database connection issues

    Using localhost in Docker Environment

    One of the most common issues users encounter is trying to connect to a locally hosted database using localhost from within a Docker container.

    Problem:

    When running Gluesync in Docker and trying to connect to a database running on your host machine, using localhost or 127.0.0.1 in your connection string won’t work. This is because localhost inside the container refers to the container itself, not your host machine.

    Solution:

    Use host.docker.internal instead of localhost in your connection string. This special DNS name resolves to the host machine’s IP address from within Docker containers.

    Example connection strings
    # ❌ Wrong (won't work)
jdbc:postgresql://localhost:5432/mydb

# ✅ Correct (will work)
jdbc:postgresql://host.docker.internal:5432/mydb
    If you’re using Docker Compose, you can also use the service name defined in your docker-compose.yml file to reference other containerized services.

    For more information about container networking, please refer to the following link.

    Connection refused error

    If you’re getting a Connection refused error when trying to connect to your Gluesync instance, similar to the following error message:

    Error: "Connection refused. Verify the connection properties. Make sure that an instance of "Database name" is running on the host and accepting TCP/IP connections at the port. Make sure that TCP connections to the port are not blocked by a firewall"

    Follow this checklist to identify and resolve the connection issue:

    1. Verify database location and accessibility

    • Where is your database running?

      • On the same machine as Gluesync?

      • On a remote server?

      • In a Docker container?

    If running locally with Docker, remember to use host.docker.internal instead of localhost in your connection string.

    2. Check network configuration

    • Firewall settings:

      • Windows Firewall: ensure DBMS port is open

      • Cloud provider firewalls: check security group rules

      • Corporate firewalls: verify with your IT team

    • SQL Server network configuration:

      • TCP/IP protocol must be enabled (for example in MS SQL Server, Named Pipes are not supported)

      • DBMS default port should be listening

    Enabling TCP/IP protocol
    1. Open SQL Server Configuration Manager
2. Navigate to SQL Server Network Configuration > Protocols
3. Ensure TCP/IP is set to 'Enabled'
4. Restart SQL Server service

    3. Verify SQL Server configuration

    • Authentication mode:

      • Mixed Mode authentication must be enabled

      • DBMS credentials should have proper permissions, check the respective agent documentation to know more about which permissions are required

    • External connections:

      • Remote connections must be allowed

      • Server should be configured to accept external connections

    4. Connection string verification

    • Check these components:

      • Server name/IP is correct

      • Port number matches your DBMS server configuration

      • Authentication credentials are valid

      • Database name exists and is spelled correctly

    5. Common solutions

    Problem Solution

    Using localhost in Docker

    Replace with host.docker.internal

    TCP/IP disabled

    Enable TCP/IP protocol (like for example in case of a MS SQL Server via its Configuration Manager)

    Firewall blocking

    Add inbound rule for the specific DBMS port, like 1433 for example (or your custom port)

    DBMS server not accepting remote connections

    Enable 'Allow remote connections' in your server properties

    Quick start: checking for errors

    1. Log into Gluesync Web UI (port 1717)

    2. Look for the bell icon (🔔) in the top navigation

    3. Check notifications sorted by severity

    For Users

    Using Notifications and alerts

    Notifications and alerts is your first stop for checking system status and errors:

    Type Description Action Required

    Error đŸšĢ

    Critical issues requiring immediate attention

    Yes - Contact admin if persistent

    Warning ⚠ī¸

    Potential issues or performance degradation

    Monitor and report if persistent

    Info ℹī¸

    System updates and general information

    No immediate action needed

    Common issues and solutions

    Connection problems

    • What you’ll see: "Cannot connect to source/target"

    • Quick checks:

      • Is the source system accessible?

      • Are your credentials correct?

      • Is there a network issue?

    • What to do:

      • Verify your connection settings

      • Check your access permissions

      • Contact IT if issues persist

    Data sync delays

    • What you’ll see: Data not updating or slow updates

    • Quick checks:

      • Check source system status

      • Look for warning notifications

      • Review recent changes

    • What to do:

      • Verify source data exists

      • Check for filtering rules

      • Create indexes if needed

      • Report persistent delays

    Error messages

    • What you’ll see: Red error notifications

    • Quick checks:

      • Note the exact error message

      • Check when it started

      • Look for related warnings

    • What to do:

      • Take a screenshot of the error

      • Document the steps to reproduce

      • Report to support team

    When to contact support

    Contact MOLO17 support team when:

    1. You see persistent error notifications

    2. Data synchronization is significantly delayed

    3. You notice unexpected data changes

    4. The web interface is unresponsive

    Always include these details when reporting issues:

    • Exact error message

    • Time of occurrence

    • Steps to reproduce

    • Screenshots if possible

    For system administrators

    This section covers advanced troubleshooting for system administrators, including log collection and system maintenance.

    Collecting logs in Docker Compose

    # View logs for all services
docker compose logs

# View logs for a specific service
docker compose logs core-hub

# Follow logs in real-time
docker compose logs -f

# Get last 500 lines with timestamps
docker compose logs --tail=500 -t

# Save logs to a file
docker compose logs > gluesync-logs.txt

    Use docker compose ps to list all running services and their status before collecting logs.

    Collecting logs in Kubernetes

    # Get pods in gluesync namespace
kubectl get pods -n gluesync

# View logs for a specific pod
kubectl logs <pod-name> -n gluesync

# Follow logs in real-time
kubectl logs -f <pod-name> -n gluesync

# Get logs from previous container instance
kubectl logs <pod-name> -n gluesync --previous

# Get logs from all containers in a pod
kubectl logs <pod-name> -n gluesync --all-containers=true

# Export logs to a file
kubectl logs <pod-name> -n gluesync > pod-logs.txt

    For persistent log storage, consider setting up a logging solution like ELK Stack or Prometheus/Grafana.

    Advanced log collection

    # Collect logs from multiple pods
kubectl get pods -n gluesync -o name | xargs -I {} kubectl logs {} -n gluesync > all-pods-logs.txt

# Get logs with specific label
kubectl logs -l app=gluesync -n gluesync

# Get logs since specific time
kubectl logs <pod-name> -n gluesync --since=24h

    System maintenance

    • Regular Checks

      • Monitor system resources

      • Check for system updates

      • Review error logs

      • Verify backup systems

    • Performance optimization

      • Analyze resource usage

      • Tune configuration parameters

      • Optimize network routes

      • Adjust scaling settings

    Debug mode

    To enable debug logging, you’ll need to modify the Logback configuration file. First, set the LOG_CONFIG_FILE environment variable to point to your custom configuration:

    LOG_CONFIG_FILE=/path/to/logback.xml

    Then create or modify your logback.xml file with debug level logging:

    <?xml version="1.0" encoding="UTF-8"?>
<included>
   <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
       <encoder>
           <pattern>
               %d{yyyy-MM-dd'T'HH:mm:ss.SSS} [%t] %c{0} %p - %msg%n
           </pattern>
       </encoder>
   </appender>
   <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
       <file>/var/log/gluesync/gluesync.log</file>
       <rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">
           <fileNamePattern>/var/log/gluesync/archived/gluesync.%d{yyyy-MM-dd}.%i.log</fileNamePattern>
           <maxFileSize>10MB</maxFileSize>
           <totalSizeCap>20GB</totalSizeCap>
           <maxHistory>60</maxHistory>
       </rollingPolicy>
       <encoder>
           <pattern>%d{yyyy-MM-dd'T'HH:mm:ss.SSS} %c{1} %p %m%n</pattern>
       </encoder>
   </appender>
   <!-- Set debug level for Gluesync components -->
   <logger name="com.molo17.gluesync" level="DEBUG" additivity="false">
       <appender-ref ref="CONSOLE"/>
       <appender-ref ref="FILE"/>
   </logger>
</included>

    For more details about logging configuration, see our Logging Guide.

    Support resources