ruby/ruby · error · Bundler::PathError

There was an error while trying to use the path `#{somepath}

Error message

There was an error while trying to use the path `#{somepath}`.
The error message was: #{e.message}.

What it means

Bundler raises this PathError while expanding the filesystem path of a `:path` source (e.g. `gem "mygem", path: "..."` in a Gemfile). The underlying `Pathname#expand_path(root_path)` call raised ArgumentError, which almost always means the path string itself is unusable: it contains a NUL byte, or it starts with `~someuser` for a user that does not exist on the machine. The original Ruby message is embedded in the error text and the exception is logged at debug level via Bundler.ui.debug.

Source

Thrown at lib/bundler/source/path.rb:132

      def root
        Bundler.root
      end

      def expanded_original_path
        @expanded_original_path ||= expand(original_path)
      end

      private

      def expanded_path
        @expanded_path ||= expand(path)
      end

      def expand(somepath)
        somepath.expand_path(root_path)
      rescue ArgumentError => e
        Bundler.ui.debug(e)
        raise PathError, "There was an error while trying to use the path " \
          "`#{somepath}`.\nThe error message was: #{e.message}."
      end

      def lockfile_path
        return relative_path(original_path) if original_path.absolute?
        expand(original_path).relative_path_from(root)
      end

      def app_cache_path(custom_path = nil)
        @app_cache_path ||= Bundler.app_cache(custom_path).join(app_cache_dirname)
      end

      def has_app_cache?
        SharedHelpers.in_bundle? && app_cache_path.exist?
      end

      def load_gemspec(file)
        return unless spec = Bundler.load_gemspec(file)

View on GitHub (pinned to 0e5b888e1c)

Solutions

1. Fix the path string in the Gemfile so it is a plain relative or absolute path with no NUL bytes, control characters, or ~user references
2. Replace `~user/...` with a concrete absolute path, or expand it yourself: `File.expand_path("~/gems/foo")` at Gemfile load time so failures surface immediately
3. Print and inspect the exact interpolated value of any ENV variable used to build the path before running bundle install
4. If the value comes from tooling, sanitize it before it reaches the Gemfile: reject strings containing "\0" and validate against a strict pattern

Example fix

# before
gem "mygem", path: "~#{ENV['DEPLOY_USER']}/gems/mygem"

# after
gem "mygem", path: File.expand_path("vendor/mygem", __dir__)

# Validate a :path string before bundler expands it
def valid_bundler_path?(p, base = Dir.pwd)
  s = p.to_s
  return false if s.empty? || s.include?("\0")
  begin
    File.expand_path(s, base)
    true
  rescue ArgumentError # bad ~user reference
    false
  end
end

abort "invalid path #{path.inspect}" unless valid_bundler_path?(path)

begin
  Bundler::Source::Path.new("path" => some_path)
rescue Bundler::PathError => e
  abort "Bad :path value: #{e.message}" # message carries the original ArgumentError
end

When it happens

Trigger: A Gemfile `:path` option (or programmatic use of Bundler::Source::Path) whose string contains a "\0" NUL byte or a `~nonexistentuser/...` prefix; paths built from environment variables that are empty, unset, or carry control characters; Gemfiles copied between machines whose home-directory prefixes differ.

Common situations: Gemfiles hand-edited or generated by scripts that inject bad characters; `path: "~#{ENV['USER']}/gems/foo"` when USER is empty or the account does not exist on the CI machine; strings that passed through binary processing and kept an embedded NUL; developer machines vs deploy hosts with different usernames.

Related errors

• The path `#{expanded_path}` is not a directory.
• The path `#{expanded_path}` does not exist.
• Could not install to path `#{bundle_path}` because a file al
• `#{group}` group could not be found.
• Could not find gem '#{gem_name}'.

AI-assisted analysis of ruby/ruby@0e5b888e1c (2026-08-21). Data as JSON: /api/errors/769399c6ae276be9. Report an issue: GitHub.