jordansissel/fpm · error · FPM::InvalidPackageConfiguration

The version looks invalid for Debian packages. Debian versio

Error message

The version looks invalid for Debian packages. Debian version field must contain only alphanumerics and . (period), + (plus), - (hyphen) or ~ (tilde). I have '#{@version}' which which isn't valid.

What it means

Debian policy requires the Version field to match [epoch:]upstream[-revision] using only alphanumerics and . + - ~ characters. fpm validates the version string in the deb output/input path (VERSION_FIELD_PATTERN); it first auto-strips a single leading 'v' with a warning, then raises FPM::InvalidPackageConfiguration if the remainder still fails the pattern.

Source

Thrown at lib/fpm/package/deb.rb:332

      @name = @name.gsub(/[ ]/, "-")
    end

    return @name
  end # def name

  def prefix
    return (attributes[:prefix] or "/")
  end # def prefix

  def version
    if @version.kind_of?(String)
      if @version.start_with?("v") && @version.gsub(/^v/, "") =~ /^#{VERSION_FIELD_PATTERN}$/
        logger.warn("Debian 'Version' field needs to start with a digit. I was provided '#{@version}' which seems like it just has a 'v' prefix to an otherwise-valid Debian version, I'll remove the 'v' for you.")
        @version = @version.gsub(/^v/, "")
      end

      if @version !~ /^#{VERSION_FIELD_PATTERN}$/
        raise FPM::InvalidPackageConfiguration, "The version looks invalid for Debian packages. Debian version field must contain only alphanumerics and . (period), + (plus), - (hyphen) or ~ (tilde). I have '#{@version}' which which isn't valid."
      end
    end

    return @version
  end

  def input(input_path)
    extract_info(input_path)
    extract_files(input_path)
  end # def input

  def extract_info(package)
    compression = `#{ar_cmd[0]} t #{package}`.split("\n").grep(/control.tar/).first.split(".").last
    case compression
      when "gz"
        controltar = "control.tar.gz"
        compression = "-z"
      when "bzip2","bz2"

View on GitHub (pinned to b6d77ba72a)

Solutions

1. Sanitize the version: replace invalid characters, typically _ -> ~ (Debian's ordering marker for pre-releases)
2. Strip a leading 'v' yourself (or rely on fpm's auto-strip once the rest is valid)
3. Format epochs and revisions correctly as 1:2.3.4-1 (integer epoch, single colon)
4. If converting from another package type, pass an explicit --version with a sanitized value

Example fix

# before
fpm -s dir -t deb -n foo --version 1.2.3_beta .
# -> version looks invalid for Debian packages

# after
fpm -s dir -t deb -n foo --version 1.2.3~beta .
# leading v is auto-stripped: --version v1.2.3 also works

DEB_VERSION_RE = /\A(?:(?:[0-9]+):)?(?:[A-Za-z0-9+~.-]+)(?:-[A-Za-z0-9+~.]+)?\z/

def sanitize_deb_version(v)
  v = v.sub(/\Av/, '')                 # strip a single leading v
  v.tr('_', '~')                       # common fix for dev releases like 1.2_3
end

abort "invalid deb version '#{v}'" unless sanitize_deb_version(v) =~ DEB_VERSION_RE

def valid_deb_version?(v)
  v = v.sub(/\Av/, '')
  !(v =~ /\A(?:(?:[0-9]+):)?[A-Za-z0-9+~.-]+(?:-[A-Za-z0-9+~.]+)?\z/).nil?
end

begin
  pkg.output(path)
rescue FPM::InvalidPackageConfiguration => e
  raise unless e.message =~ /version looks invalid/
  pkg.version = sanitize_deb_version(pkg.version)   # strip v, _ -> ~
  retry
end

When it happens

Trigger: Passing --version (or a converted package carrying a version) containing characters outside [A-Za-z0-9.+~-], e.g. 1.2.3_beta (underscore), '1.0 rc1' (space), 1:2.0:x (extra colon), or 'v' followed by another invalid string. The auto-fix only handles exactly one leading 'v' before an otherwise valid version.

Common situations: Packaging git tags like v1.2.3-rc.1 (handled) vs v1.2.3+build 4 (space fails); upstream versions with underscores from dev releases; converting from gem/npm where versions like '2.0.0-beta.1' are valid but '2.0.0_beta' is not; double colons from templated version strings.

Related errors

• Found invalid Provides field values (#{provide.inspect}). Th
• Unsupported version string '#{parse.call("Version")}'
• Invalid systemd unit file extension: #{extname}. Expected on
• deb compression value of '#{value}' is invalid. Must be one
• Missing control.tar in deb source package #{package}

AI-assisted analysis of jordansissel/fpm@b6d77ba72a (2026-08-21). Data as JSON: /api/errors/8d55d41c8eab763f. Report an issue: GitHub.