EugenMayer/docker-sync · error

Fswatch is not expected to run on platforms other then MacOS

Error message

Fswatch is not expected to run on platforms other then MacOS

What it means

Dependencies::Fswatch.available? starts with 'forbid! unless Environment.mac?' (lib/docker-sync/dependencies/fswatch.rb:7), and forbid! raises UNSUPPORTED. The fswatch file watcher is treated as macOS-only, so probing or ensuring that dependency on Linux or Windows aborts with this error instead of returning false. It is reached directly via watch_strategy: fswatch, and indirectly because the rsync sync strategy's default watch strategy is fswatch (default_watch_strategy, project_config.rb:153).

Source

Thrown at lib/docker-sync/dependencies/fswatch.rb:21

    module Fswatch
      UNSUPPORTED = 'Fswatch is not expected to run on platforms other then MacOS'

      def self.available?
        forbid! unless Environment.mac?
        return @available if defined? @available
        @available = find_executable0('fswatch')
      end

      def self.ensure!
        return if available?

        PackageManager.install_package('fswatch')
        puts "please restart docker sync so the installation of fswatch takes effect"
        exit(1)
      end

      def self.forbid!
        raise UNSUPPORTED
      end
    end
  end
end

View on GitHub (pinned to 4eab6de164)

Solutions

1. On non-macOS hosts, set an explicit watch_strategy: dummy (or unison) on every rsync sync so the fswatch default is never used.
2. Prefer sync_strategy: native on Linux; its default watch strategy is dummy and no fswatch probe happens.
3. Keep rsync plus fswatch configs on macOS machines only, and exclude them from Linux CI.
4. Guard any direct Fswatch.available?/ensure! call with a host_os darwin check.

Example fix

# before (runs on Linux; fswatch is macOS-only)
syncs:
  appcode-sync:
    src: './src'
    sync_strategy: 'rsync'   # default watcher for rsync is fswatch -> raises

# after
syncs:
  appcode-sync:
    src: './src'
    sync_strategy: 'rsync'
    watch_strategy: 'dummy'

# pick the watcher per OS before building options
mac = RbConfig::CONFIG['host_os'].include?('darwin')
options['watch_strategy'] = mac ? 'fswatch' : 'dummy'

def fswatch_supported?
  RbConfig::CONFIG['host_os'].include?('darwin')
end

begin
  DockerSync::Dependencies::Fswatch.available?
rescue RuntimeError => e
  raise unless e.message == DockerSync::Dependencies::Fswatch::UNSUPPORTED
  # non-mac host: select another watch strategy instead
end

When it happens

Trigger: Running docker-sync on a non-macOS host where any sync has watch_strategy: fswatch, or sync_strategy: rsync with no explicit watch_strategy (its default resolves to fswatch); also any direct call to Dependencies::Fswatch.available? or ensure! off macOS.

Common situations: A config authored on a Mac executed on a Linux CI runner or a teammate's Linux machine; macOS tutorials pasted into Linux setups; docker-toolbox-era rsync plus fswatch combinations.

Related errors

• No docker-sync.yml configuration found in your path ( traver
• Your docker-sync.yml file does not include a version: "2"(Ad
• Your docker-sync.yml file does not match the required versio
• no syncs defined
• Unknown sync_strategy #{@options['sync_strategy']}

AI-assisted analysis of EugenMayer/docker-sync@4eab6de164 (2026-08-23). Data as JSON: /api/errors/6a3877f8c1c82f86. Report an issue: GitHub.