Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

Rails stops with AdapterNotSpecified because the database settings have no adapter

ErrorActiveRecord::AdapterNotSpecified: database configuration does not specify adapter

Short answer

Rails looked up the database settings for the current environment and found no adapter. Either that environment's entry in database.yml has no adapter line, the environment has no entry at all, or the DATABASE_URL that was meant to supply the adapter is not set where the command runs. Add adapter: postgresql, or fix the environment and the variable.

  • Applies to Ruby on Rails 7.2, Ruby on Rails 8.0, PostgreSQL 16, PostgreSQL 17
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Print the environment Rails will use, whether DATABASE_URL is set (without showing it), and the top-level keys and adapter lines of database.yml. These three facts separate the causes below.

    echo "RAILS_ENV=${RAILS_ENV:-(not set, Rails uses its default)}"
    [ -n "$DATABASE_URL" ] && echo "DATABASE_URL is set" || echo "DATABASE_URL is not set"
    grep -n -E "^[a-z_]+:|adapter" config/database.yml
  2. 2Match what you see, then jump to its fix

    1. 1ActiveRecord::AdapterNotSpecified: database configuration does not specify adapterThe entry for this environment has no adapterFix
    2. 2The `<name>` database is not configured for the `<environment>` environment.The environment name has no entry in database.yml, and DATABASE_URL is not setFix
    3. 3The app works in one place (a server, a platform dyno) and fails in another: a build step, a CI job, a shell on a laptopDATABASE_URL is missing where the command runsFix

What does the error look like?

  • ActiveRecord::AdapterNotSpecified: database configuration does not specify adapter
  • The `<name>` database is not configured for the `<environment>` environment.

Cause 1 of 3

The entry for this environment has no adapter

1Check

The file the Rails generator writes for PostgreSQL keeps adapter: postgresql in a default block, and each environment pulls it in with <<: *default. An environment entry that lost that merge line, or a default block that lost its adapter line, leaves the entry with no adapter. In a Rails 8 production section with nested entries, each of them needs the adapter too: the generated file shares it through an anchor.

grep -n -E "adapter|<<:|&default|&primary" config/database.yml

2Fix

Put the adapter back in the shared default block and make every environment merge it. Keep the indentation: YAML nests by spaces.

default: &default
  adapter: postgresql
  encoding: unicode

development:
  <<: *default
  database: myapp_development

production:
  <<: *default
  database: myapp_production

3Verify

Ask Rails for the schema version of the environment that failed. It prints a number instead of raising the error.

RAILS_ENV=production bin/rails db:version

Confirmed by raw.githubusercontent.com

Did this fix it?

Cause 2 of 3

The environment name has no entry in database.yml, and DATABASE_URL is not set

1Check

Rails picks the entry named after the current environment. A typo in RAILS_ENV, a custom environment such as staging that was never added to the file, or a tool that starts in the default environment all lead here. If DATABASE_URL is set, Rails builds a primary configuration from it for the current environment, so the error only appears when neither source exists.

echo "RAILS_ENV=$RAILS_ENV"
grep -n -E "^[a-z_]+:" config/database.yml

2Fix

Either start Rails in an environment the file defines, or add an entry for the one you use, merged from the default block, or provide DATABASE_URL.

# config/database.yml
staging:
  <<: *default
  database: myapp_staging

# or pick an environment that exists
RAILS_ENV=production bin/rails db:version

3Verify

The command prints the schema version for that environment.

RAILS_ENV=staging bin/rails db:version

Confirmed by raw.githubusercontent.com

Did this fix it?

Cause 3 of 3

DATABASE_URL is missing where the command runs

1Check

When DATABASE_URL is present, Rails uses it as the connection information whatever the environment is, and merges in other options from database.yml. If your production entry leaves the adapter and database to the variable, any command that runs without it has no adapter. On Heroku, Heroku Postgres adds the connection string as a config var for the app.

# on Heroku: show only the name of the variable, not the secret
heroku config | grep -o "^DATABASE_URL"

2Fix

Set the variable for that command, or attach the database, so the platform sets it. If you want database.yml to stand on its own, put adapter: postgresql in the production entry. When DATABASE_URL is set, the values it carries win.

DATABASE_URL="postgres://user:password@localhost/myapp_production" RAILS_ENV=production bin/rails db:version

3Verify

The command prints a schema version for the same environment.

RAILS_ENV=production bin/rails db:version

Confirmed by devcenter.heroku.com

Did this fix it?

How do I stop it coming back?

  • Start from the generated database.yml and keep the adapter in one default block that every environment merges.
  • Name each environment that really exists in database.yml, and keep RAILS_ENV set to one of them in every deploy and CI step.
  • List the environment variables each command needs (DATABASE_URL, RAILS_ENV) in the deploy notes, and set them for build and release steps as well as for the running app.
  • Use the url key in database.yml only when you mean to ignore DATABASE_URL: an explicit url skips the merge with the variable.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Related fixes

Back end

rails db:create stops with Couldn't create database

Couldn't create database for {"adapter"=>"postgresql"

rails db:create asks PostgreSQL to run CREATE DATABASE, so the connection role needs the CREATEDB attribute or superuser rights.

3 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.