Fix Ruby Gems Encoding Error on Windows

I recently ran into an issue while working with Ruby on Windows, and it really threw me off. When I tried running some Ruby commands, I kept getting this error:

It became clear that something was wrong with my setup. I suspected the problem had to do with my PATH settings, so I checked my gem environment (gem env). That’s when I noticed the issue: my Windows User folder name contains a special character — “ã” in “Tiago Galvão” — and Ruby doesn’t seem to like that.

Error Code:

codeerror_data = {
  error: 'invalid byte sequence in UTF-8 (ArgumentError)',
  backtrace: [
    'C:/Ruby31-x64/lib/ruby/3.1.0/pathname.rb:52:in `match?`',
    'C:/Ruby31-x64/lib/ruby/3.1.0/pathname.rb:52:in `chop_basename`',
    'C:/Ruby31-x64/lib/ruby/3.1.0/pathname.rb:376:in `plus`',
    'C:/Ruby31-x64/lib/ruby/3.1.0/pathname.rb:356:in `+`',
    'C:/Ruby31-x64/lib/ruby/3.1.0/pathname.rb:422:in `join`',
    'C:/Ruby31-x64/lib/ruby/site_ruby/3.1.0/bundler/settings.rb:445:in `global_config_file`',
    'C:/Ruby31-x64/lib/ruby/site_ruby/3.1.0/bundler/settings.rb:93:in `initialize`',
    'C:/Ruby31-x64/lib/ruby/site_ruby/3.1.0/bundler.rb:343:in `new`',
    'C:/Ruby31-x64/lib/ruby/site_ruby/3.1.0/bundler.rb:343:in `settings`',
    'C:/Ruby31-x64/lib/ruby/site_ruby/3.1.0/bundler/env.rb:20:in `report`',
    'C:/Ruby31-x64/lib/ruby/site_ruby/3.1.0/bundler/friendly_errors.rb:71:in `request_issue_report_for`',
    'C:/Ruby31-x64/lib/ruby/site_ruby/3.1.0/bundler/friendly_errors.rb:50:in `log_error`',
    'C:/Ruby31-x64/lib/ruby/site_ruby/3.1.0/bundler/friendly_errors.rb:123:in `rescue in with_friendly_errors`',
    'C:/Ruby31-x64/lib/ruby/site_ruby/3.1.0/bundler/friendly_errors.rb:115:in `with_friendly_errors`',
    'C:/Ruby31-x64/lib/ruby/gems/3.1.0/gems/bundler-2.3.15/exe/bundle:36:in `<main>`'
  ]
}

gem_env = {
  version_info: {
    rubygems_version: '3.3.15',
    ruby_version: '3.1.2 (2022-04-12 patchlevel 20) [x64-mingw-ucrt]'
  },
  directories: {
    installation_directory: 'C:/Ruby31-x64/lib/ruby/gems/3.1.0',
    user_installation_directory: 'C:/Users/Tiago Galvão/.local/share/gem/ruby/3.1.0',
    ruby_executable: 'C:/Ruby31-x64/bin/ruby.exe',
    git_executable: 'C:/Program Files/Git/cmd/git.EXE',
    executable_directory: 'C:/Ruby31-x64/bin',
    spec_cache_directory: 'C:/Users/Tiago Galvão/.local/share/gem/specs',
    system_configuration_directory: 'C:/ProgramData'
  },
  platforms: [
    'ruby',
    'x64-mingw-ucrt'
  ]
}

How can I change the USER INSTALLATION DIRECTORY and SPEC CACHE DIRECTORY of my gem env to run Rails commands on Windows?
I want to set the directories to a location without special characters in the path or configure Ruby to accept special characters in my username. How can I achieve this?

To resolve the Encoding Error (windows) issue in Ruby on Windows, follow these steps carefully to change the USER INSTALLATION DIRECTORY and SPEC CACHE DIRECTORY for your Ruby environment. Here’s a step-by-step guide to address this issue effectively.

Solution Steps:

Change Gem Installation Paths Using GEM_HOME and GEM_PATH Environment Variables

1. Set the New Gem Paths (Without Special Characters)
   • Create a new folder for Ruby gems without special characters. For example: codeC:\RubyGems
   • You’ll store your gems in this new directory to avoid encoding issues.
2. Set Environment Variables (GEM_HOME and GEM_PATH):
   • Press Win + R, type sysdm.cpl, and press Enter.
   • Go to the Advanced tab → Environment Variables.
   • Under User variables, click New and add the following variables:
     • GEM_HOME: C:\RubyGems
     • GEM_PATH: C:\RubyGems
     • PATH: Add C:\RubyGems\bin (if it isn’t already in the PATH).
3. Test if Changes Were Successful:
   • Open Command Prompt or PowerShell and run: codeecho %GEM_HOME% echo %GEM_PATH%
   • Make sure these return the new directory paths.
4. Reinstall Bundler and Other Gems:
   • Now, in the terminal, run: codegem install bundler
   • Verify if the gems are being installed to the new path using: codegem env

Use bundle config to Modify Paths

Alternatively, you can modify the gem configuration using Bundler’s config.

1. Change the User Gem Installation Directory:
   • Run the following commands in Command Prompt or PowerShell: codebundle config set --global path C:/RubyGems
2. Verify the Changes:
   • Check if Bundler recognizes the new path: codebundle config

Force UTF-8 Encoding

If changing paths is not an option, you can try forcing UTF-8 encoding.

1. Modify Your Ruby Environment:
   • Open your Ruby installation’s command prompt and run: codeset RUBYOPT=-EUTF-8
2. Test Your Setup:
   • Try creating a new Rails app again: coderails new my_app

Create a New Local User Account Without Special Characters

If you can’t modify the path and forcing encoding doesn’t work, creating a new user account may be your last resort.

1. Create a New User:
   • Open Settings → Accounts → Family & other users → Add someone else to this PC.
   • Create a new user without any special characters (e.g., TiagoGalvao).
2. Install Ruby and Rails for the New User:
   • Log in with the new user and install Ruby and Rails under this account.

Final Though

Using the environment variables to change the installation paths is the safest way to resolve the encoding issue caused by special characters in your username. If that doesn’t work, forcing UTF-8 encoding or creating a new user might be necessary alternatives.