Introduction

The Ruby error uninitialized constant AWS (NameError) usually means your code is referring to the old AWS namespace even though the installed AWS SDK version exposes the newer Aws namespace, or the required gem was never loaded at all. The important clue is the capitalization: AWS and Aws are not the same constant in Ruby.

So the fix is usually one of two things: require the right gem, or change the namespace to match the version of the AWS SDK you are actually using.

Old Namespace Versus Current Namespace

Older AWS SDK for Ruby versions used AWS. Modern versions use Aws.

This old-style code belongs to the older SDK generation:

require 'aws-sdk'
s3 = AWS::S3.new

Modern SDK usage looks like this instead:

1require 'aws-sdk-s3'
2
3s3 = Aws::S3::Client.new(region: 'us-east-1')
4puts s3.class.name

If your gem version is current but your code still references AWS::S3, Ruby raises uninitialized constant AWS because that constant no longer exists in the expected way.

Check Which Gem You Installed

If you are using Bundler, inspect Gemfile and Gemfile.lock. You may have a service-specific gem such as aws-sdk-s3 rather than the older omnibus gem.

source 'https://rubygems.org'

gem 'aws-sdk-s3'

Then in your code:

require 'aws-sdk-s3'

If the gem is not installed or not required, the namespace will not be available even if the code spelling is correct.

Make the Version and Code Match

A clean troubleshooting sequence is:

1. check the gem in Gemfile
2. check the require statement
3. check whether the code uses Aws or AWS
4. align all three to the same SDK generation

In most current Ruby applications, the right fix is to move to Aws::... namespaces.

Check the Service Namespace You Actually Need

Modern AWS SDK usage is usually service-specific. For example, S3 code should often use Aws::S3::Client and DynamoDB code should use Aws::DynamoDB::Client. If a project loads only aws-sdk-s3, then only the S3 client namespace is relevant. Looking for a generic top-level AWS constant in that setup is a version mismatch, not a loading success.

That also means a successful fix is often very small: change the constant name, require the correct service gem, and instantiate the modern client class explicitly.

If the project uses Bundler, always run the code through bundle exec as well so the intended gem set is actually loaded.

Do Not Guess from Old Blog Posts

A lot of old AWS Ruby examples still circulate online. If you copy an old snippet that says AWS::S3.new into a project using current gems, the code will fail even though the logic looks otherwise reasonable.

That is why AWS SDK errors often come from version drift rather than from credentials or service configuration.

Common Pitfalls

• Using AWS::... syntax with modern aws-sdk-* gems.
• Requiring the wrong gem name or forgetting to require the service gem at all.
• Reading old tutorials without checking which SDK generation they target.
• Assuming the error is about AWS credentials when the namespace itself was never loaded.
• Mixing old and new AWS SDK examples in the same codebase.

Summary

• 'uninitialized constant AWS usually means a namespace mismatch or missing require.'
• Old Ruby SDK code used AWS; modern SDK code uses Aws.
• Make sure the gem, the require statement, and the constant name all match.
• In current projects, prefer service gems such as aws-sdk-s3 and namespaces such as Aws::S3::Client.
• Be cautious with old AWS Ruby examples copied from outdated sources.