EugenMayer/docker-sync · error

Your docker-sync.yml file does not include a version: "2"(Ad

Error message

Your docker-sync.yml file does not include a version: "2"(Add this if you migrated from docker-sync 0.1.x)

What it means

The v2 config format requires a top-level version key (REQUIRED_CONFIG_VERSION = '2' in lib/docker-sync/config/project_config.rb:11). validate_config! raises ERROR_MISSING_CONFIG_VERSION when the YAML was found and parsed fine but contains no 'version' key at all: the signature of a config written for docker-sync 0.1.x, which the error text calls out explicitly. This is distinct from the neighboring line-76 check, which fires when the key exists but holds the wrong value.

Source

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

    def rsync_required?
      # 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)

View on GitHub (pinned to 4eab6de164)

Solutions

1. Add version: "2" as the first line of docker-sync.yml (the unquoted integer 2 also passes because the check compares value.to_s).
2. If migrating a 0.1.x config, also move your sync entries under a top-level syncs: key.
3. When unsure of the file shape, copy example/docker-sync.yml from the docker-sync repository and re-add your syncs.

Example fix

# before (docker-sync.yml)
syncs:
  appcode-sync:
    src: './src'

# after
version: "2"
syncs:
  appcode-sync:
    src: './src'

require 'yaml'

raw = YAML.safe_load(File.read('docker-sync.yml')) || {}
abort 'docker-sync.yml: missing version key' unless raw.key?('version')
config = DockerSync::ProjectConfig.new

begin
  DockerSync::ProjectConfig.new
rescue RuntimeError => e
  raise unless e.message == DockerSync::ProjectConfig::ERROR_MISSING_CONFIG_VERSION
  # parsed fine but no version key: add version: "2" and retry
end

When it happens

Trigger: ProjectConfig.new finds and parses docker-sync.yml, but the resulting hash has no 'version' key: for example a file containing only a syncs: block, or a pre-0.2.x config migrated as-is. Applies to both file-loaded configs and configs passed via config_string.

Common situations: Migrating from docker-sync 0.1.x; writing a first config from an outdated tutorial that omits the version header; deleting the line as apparent noise while editing.

Related errors

• Your docker-sync.yml file does not match the required versio
• 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/3a2d79adcefb374f. Report an issue: GitHub.