EugenMayer/docker-sync · error

Your docker-sync.yml file does not match the required versio

Error message

Your docker-sync.yml file does not match the required version (2).

What it means

The config has a version key, but its value does not equal the required '2': validate_config! compares config['version'].to_s == REQUIRED_CONFIG_VERSION ('2', defined at lib/docker-sync/config/project_config.rb:11, checked at line 76). docker-sync refuses configs of a different format generation instead of misinterpreting them. Because the comparison goes through to_s, the integer 2 is accepted; '1', '2.0', 3, or 'two' all raise.

Source

Thrown at lib/docker-sync/config/project_config.rb:76

      # noinspection RubyUnusedLocalVariable
      config['syncs'].any? { |name, sync_config|
        sync_config['sync_strategy'] == 'rsync'
      }
    end

    def fswatch_required?
      # noinspection RubyUnusedLocalVariable
      config['syncs'].any? { |name, sync_config|
        sync_config['watch_strategy'] == 'fswatch'
      }
    end

    private

      def validate_config!
        raise error_missing_given_config if config.nil?
        raise ERROR_MISSING_CONFIG_VERSION unless config.key?('version')
        raise ERROR_MISMATCH_CONFIG_VERSION unless config['version'].to_s == REQUIRED_CONFIG_VERSION
        raise ERROR_MISSING_SYNCS unless config.key?('syncs')

        validate_syncs_config!
      end

      def validate_syncs_config!
        config['syncs'].each do |name, sync_config|
          validate_sync_config(name, sync_config)
        end
      end

      def validate_sync_config(name, sync_config)
        config_mandatory = %w[src]
        #TODO: Implement autodisovery for other strategies
        config_mandatory.push('sync_host_port') if sync_config['sync_strategy'] == 'rsync'
        config_mandatory.each do |key|
          raise ("#{name} does not have #{key} configuration value set - this is mandatory") unless sync_config.key?(key)
        end

View on GitHub (pinned to 4eab6de164)

Solutions

1. Set the value to exactly version: "2" (or the unquoted integer 2).
2. If the config was authored for a newer docker-sync, upgrade the gem (check gem list docker-sync or the VERSION file) rather than rewriting the config backward.
3. Keep the version line untouched when copying configs between projects.

Example fix

# before
version: "1"

# after
version: "2"   # the unquoted integer 2 also works (compared via to_s)

require 'yaml'

raw = YAML.safe_load(File.read('docker-sync.yml')) || {}
abort 'docker-sync.yml: version must be "2"' unless raw['version'].to_s == '2'
config = DockerSync::ProjectConfig.new

begin
  DockerSync::ProjectConfig.new
rescue RuntimeError => e
  raise unless e.message == DockerSync::ProjectConfig::ERROR_MISMATCH_CONFIG_VERSION
  # version key present but wrong: set it to exactly "2"
end

When it happens

Trigger: ProjectConfig.new with version: "1" (a 0.1.x-era config that did carry a version), version: "2.0", or any other value, whether loaded from docker-sync.yml or passed via config_string.

Common situations: Running an older docker-sync gem against a config written for a newer format (or the reverse); hand-editing the value to '2.0' assuming semver; copying configs between projects pinned to different docker-sync releases.

Related errors

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

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