Skip to content

Instantly share code, notes, and snippets.

What would you like to do?
how to access subdomains locally with Rails 5

Subdomaining Localhost with Rails 5

I've been following this blog post on how to set up an api-only Rails 5 application. One of the sections talks about creating a subdomain for your api

Rails.application.routes.draw do
  constraints subdomain: "api" do
    scope module: "api" do
      namespace :v1 do
        resources :users

So that you can have namespacing and versioning like

However, this seems to cause some issues locally. At first I just kept getting back a 404 error that the route I was searching for didn't exist despite it showing up correctly when I ran rake routes

  Prefix Verb   URI Pattern             Controller#Action
v1_users GET    /v1/users(.:format)     api/v1/users#index {:subdomain=>"api"}
         POST   /v1/users(.:format)     api/v1/users#create {:subdomain=>"api"}
 v1_user GET    /v1/users/:id(.:format) api/v1/users#show {:subdomain=>"api"}
         PATCH  /v1/users/:id(.:format) api/v1/users#update {:subdomain=>"api"}
         PUT    /v1/users/:id(.:format) api/v1/users#update {:subdomain=>"api"}
         DELETE /v1/users/:id(.:format) api/v1/users#destroy {:subdomain=>"api"}

Removing constraints subdomain: "api" gave back the correct response, allowing me to prove to myself that this was indeed the issue.

Attempted solutions

  1. Editing /etc/hosts and adding in my subdomain to map to

As your machine gets started, it will need to know the mapping of some hostnames to IP addresses before DNS can be referenced. This mapping is kept in the /etc/hosts file. In the absence of a name server, any network program on your system consults this file to determine the IP address that corresponds to a host name.

I had seen a few forums that mentioned this as a solution, so I added this to /etc/hosts

When I went to http:// all I got back from Chrome was


Trying this URL on Firefox and Safari resulted in the same thing (Safari never ended up actually giving that error, it just "loaded" the page indefinitely).

  1. Using and

I think this started with Tim Pope's invention of, which was simply a public domain pointed at (localhost). and are just spawns of that same idea since both are shorter and less offensive.

Unfortunately, returns the same connection refused error as mentioned above and hangs indefinitely.

  1. Changing proxy settings in Chrome to include localhost and

Since I'm getting ERR_CONNECTION_REFUSED and not ERR_EMPTY_RESPONSE as would be expected if the domain wasn't working, I figured this was some sort of security check put in place by Chrome (and probably on Firefox and Safari too).

I tried ignoring the proxy settings for localhost,, and as per this Stack Overflow answer. Nothing changed; I continued getting the same connection error.


config.action_dispatch.tld_length sets the TLD (top-level domain) length for the application. Defaults to 1.

Setting config.action_dispatch.tld_length = 0 in config/environments/development.rb. Simple as that. This works, although I am unsure of any unseen consequences with testing and cookies in, as is noted upon in the answer.


If there is something you notice I am doing wrong, something you would like to add, or some question you may have, please feel free to comment on this post :)


This comment has been minimized.

Copy link

rmonteiro89 commented Jul 18, 2016

Thank you! It worked! =)

Did you find any downside with this solution?


This comment has been minimized.

Copy link

BigChief45 commented Sep 11, 2016

This ended so many hours of pain and suffering. Thank you so much!


This comment has been minimized.

Copy link

jjensn commented Oct 22, 2016

Cheers thanks for this post


This comment has been minimized.

Copy link

gudongfeng commented Nov 27, 2016

amazing! it worked!


This comment has been minimized.

Copy link

JBFowler commented Feb 21, 2017

👍 Thank you sir!


This comment has been minimized.

Copy link

hendricius commented Mar 9, 2017

In my case the issue was I used a symbol for the subdomain. When using string syntax, it worked :).


This comment has been minimized.

Copy link

Wynandstolp commented May 2, 2017

Thanks, I initially had some.thing.localhost which didn't work. Changing to some.thing.local did the trick.


This comment has been minimized.

Copy link

NateJBeck commented May 26, 2017

Works like a charm - thanks!


This comment has been minimized.

Copy link

viphat commented Jul 21, 2017

:(, Your solution costs me half of a day. When I revert back to config.action_dispatch.tld_length = 1, it works again.


This comment has been minimized.

Copy link

gSanchezCiarrocchi commented Mar 16, 2018



This comment has been minimized.

Copy link

cd-rum commented Mar 26, 2018

This worked great. Thank-you so much.


This comment has been minimized.

Copy link

Myusuf060696 commented Nov 1, 2018

thank you sir


This comment has been minimized.

Copy link

clementinoux commented Mar 6, 2019



This comment has been minimized.

Copy link

jtopgi commented Mar 19, 2019

You can now add your subdomain in front of localhost:3000 and it should work.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.