EugenMayer/docker-sync · error

Unknown sync_strategy #{@options['sync_strategy']}

Error message

Unknown sync_strategy #{@options['sync_strategy']}

What it means

SyncProcess#set_sync_strategy is a case over options['sync_strategy'] whose else branch raises 'Unknown sync_strategy <value>' (lib/docker-sync/sync_process.rb:54). Accepted values are exactly 'rsync', 'unison', 'native', 'native_osx': case-sensitive, no whitespace trimming. Configs that flow through ProjectConfig never see this raise because sync_strategy_for (project_config.rb:124-132) silently substitutes a platform default for unknown values, so in practice it hits code constructing SyncProcess directly with a hand-built options hash, or values valid only in other docker-sync versions.

Source

Thrown at lib/docker-sync/sync_process.rb:54

      @options = defaults.merge(options)
      @sync_strategy = nil
      @watch_strategy = nil
      set_sync_strategy
      set_watch_strategy
    end

    def set_sync_strategy
      case @options['sync_strategy']
      when 'rsync'
        @sync_strategy = DockerSync::SyncStrategy::Rsync.new(@sync_name, @options)
      when 'unison'
        @sync_strategy = DockerSync::SyncStrategy::Unison.new(@sync_name, @options)
      when 'native'
        @sync_strategy = DockerSync::SyncStrategy::Native.new(@sync_name, @options)
      when 'native_osx'
        @sync_strategy = DockerSync::SyncStrategy::NativeOsx.new(@sync_name, @options)
      else
        raise "Unknown sync_strategy #{@options['sync_strategy']}"
      end
    end

    def set_watch_strategy
      case @options['watch_strategy']
      when 'fswatch'
        @watch_strategy = DockerSync::WatchStrategy::Fswatch.new(@sync_name, @options)
      when 'dummy'
        @watch_strategy = DockerSync::WatchStrategy::Dummy.new(@sync_name, @options)
      when 'unison'
        @watch_strategy = DockerSync::WatchStrategy::Unison.new(@sync_name, @options)
      when 'remotelogs'
        @watch_strategy = DockerSync::WatchStrategy::Remote_logs.new(@sync_name, @options)
      else
        raise "Unknown watch_strategy #{@options['watch_strategy']}"
      end
    end

View on GitHub (pinned to 4eab6de164)

Solutions

1. Set sync_strategy to one of the four exact strings: 'rsync', 'unison', 'native', 'native_osx'.
2. Check casing and trailing whitespace on the value coming from YAML, ENV, or user input.
3. If the value looks right, compare it against the case list in your installed gem's lib/docker-sync/sync_process.rb; your code may assume a strategy this version does not ship.
4. Build options through ProjectConfig (it normalizes and defaults strategies) instead of hand-assembling the hash.

Example fix

# before
process = DockerSync::SyncProcess.new('appcode-sync',
  'src' => './src', 'sync_strategy' => 'native-osx')

# after
process = DockerSync::SyncProcess.new('appcode-sync',
  'src' => './src', 'sync_strategy' => 'native_osx')

ALLOWED_SYNC = %w[rsync unison native native_osx].freeze
unless ALLOWED_SYNC.include?(options['sync_strategy'])
  abort "sync_strategy must be one of: #{ALLOWED_SYNC.join(', ')}"
end
process = DockerSync::SyncProcess.new(name, options)

SYNC_STRATEGIES = %w[rsync unison native native_osx].freeze

def sync_strategy?(value)
  value.is_a?(String) && SYNC_STRATEGIES.include?(value)
end

begin
  DockerSync::SyncProcess.new(name, options)
rescue RuntimeError => e
  raise unless e.message.start_with?('Unknown sync_strategy')
  abort "unsupported sync_strategy #{options['sync_strategy'].inspect}"
end

When it happens

Trigger: DockerSync::SyncProcess.new(name, options) with options['sync_strategy'] outside the four accepted strings: 'Unison', 'native-osx', 'rsync ' (trailing space), nil, or a strategy from a different docker-sync release such as 'unison_ssh' on a version that does not ship it.

Common situations: Typos or wrong casing in hand-rolled options hashes; strategy values sourced from ENV vars or user input; code written against a newer or older gem; options mutated upstream so the key ends up nil.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• Unknown watch_strategy #{@options['watch_strategy']}
• 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

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