Rails raises PG::UndefinedTable: relation "users" does not exist
PG::UndefinedTable: ERROR: relation "users" does not existShort answer
PostgreSQL could not find a table named users in the schemas it searches for the database Rails connected to. Check which database and environment Rails uses, then compare db:migrate:status with the real tables. Run the migrations for that environment, or fix the table name or schema if the table exists elsewhere.
Fix it fast
1Find out which cause you have
Ask Rails which migrations are applied in the environment that fails. Pending ones are shown as down.
bin/rails db:migrate:status RAILS_ENV=development2Match what you see, then jump to its fix
- 1
db:migrate:status lists the create-table migration as downThe migration that creates the table was never run in this environmentFix - 2
The error appears only under bin/rails test or rspec, and the app works in developmentThe test database is behind the schemaFix - 3
Other tables work, but this model asks for a name you did not createThe model points at a different table name than the one that existsFix - 4
psql finds the table with a schema prefix (for example app.users), but Rails does notThe table is in a schema that is not on the search pathFix
- 1
What does the error look like?
PG::UndefinedTable: ERROR: relation "users" does not exist42P01 undefined_table
Cause 1 of 4
The migration that creates the table was never run in this environment
1Check
Compare the status list with the tables in the database. Production and test are separate databases from development, so a table can exist in one and be absent in the others.
bin/rails db:migrate:status
psql "$DATABASE_URL" -c '\dt'2Fix
Run the pending migrations for the environment that fails. On a new database, db:prepare creates it and loads the schema.
bin/rails db:migrate
RAILS_ENV=production bin/rails db:migrate3Verify
The status list shows every migration as up and the query works in the console.
bin/rails db:migrate:status
bin/rails runner "puts User.count"Confirmed by guides.rubyonrails.org
Cause 2 of 4
The test database is behind the schema
1Check
The test helper tries to load db/schema.rb (or db/structure.sql) into the test database and raises when migrations are pending.
bin/rails db:migrate:status RAILS_ENV=test2Fix
Bring the test database up to date. If you edited migrations that had already run, rebuild it.
bin/rails db:migrate RAILS_ENV=test
bin/rails test:db3Verify
Run the test suite again.
bin/rails testConfirmed by guides.rubyonrails.org
Cause 3 of 4
The model points at a different table name than the one that exists
1Check
Rails pluralizes the class name to find the table (User becomes users), unless the model sets its own name or a module sets a prefix.
bin/rails runner "puts User.table_name"
grep -rn "table_name" app/models2Fix
Make the migration and the model agree: rename the table in a migration, or set the name on the model.
class User < ApplicationRecord
self.table_name = "app_users"
end3Verify
The printed table name matches a table in \dt.
bin/rails runner "puts User.table_name"Confirmed by guides.rubyonrails.org
Cause 4 of 4
The table is in a schema that is not on the search path
1Check
PostgreSQL looks only in the schemas listed in search_path, which defaults to "$user", public. A table in another schema is not found by an unqualified name. Run \dt without a pattern and read the Schema column of the list.
psql "$DATABASE_URL" -c 'SHOW search_path;'
psql "$DATABASE_URL" -c '\dt'2Fix
Move the table into a schema on the search path (you need CREATE privilege on the target schema), or change search_path for the role so the schema is included.
ALTER TABLE app.users SET SCHEMA public;3Verify
Restart the app and run the query from the console.
bin/rails runner "puts User.count"Confirmed by postgresql.org
How do I stop it coming back?
- Run bin/rails db:migrate as a step of every deploy, before the new code takes traffic.
- Commit db/schema.rb after each migration so a fresh database loads the same structure.
- Keep one DATABASE_URL per environment and print which one is in use when debugging.
- Do not edit a migration that already ran elsewhere; add a new one.
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
Go database/sql fails to scan a NULL column, and stores empty strings instead of NULL
unsupported Scan, storing driver.Value type <nil> into type *string
database/sql hands a NULL to Scan as nil, and a plain *string cannot hold it, so Scan returns an error.
2 causes, each with a fixBack end
Hibernate: PersistentObjectException, detached entity passed to persist
jakarta.persistence.EntityExistsException
persist() is for new objects.
2 causes, each with a fixBack end
Knex runs out of connections and the query waits until it times out
Knex: Timeout acquiring a connection. The pool is probably full. Are you missing a .transacting(trx) call?
Every query needs a free connection from Knex's pool.
3 causes, each with a fixBack end
Node.js cannot reach PostgreSQL: connect ETIMEDOUT in production
at TCPConnectWrap.afterConnect [as oncomplete]
ETIMEDOUT means the other side never answered the connection attempt.
3 causes, each with a fixBack end
node-postgres pool times out waiting for a client
Error: timeout exceeded when trying to connect
The pool has no free client to give you.
2 causes, each with a fixBack end
node-postgres: SCRAM-SERVER-FIRST-MESSAGE client password must be a string
SASL: SCRAM-SERVER-FIRST-MESSAGE: client password must be a non-empty string
The server asked for SCRAM authentication and node-postgres had no string to hash.
4 causes, each with a fix