keepcalculator

06 Numbers and Powers

Fix a Subdomain Not Working on a VPS

Card No. 06·39744 · Updated · Standard formula, shown below

This guide walks you through diagnosing and fixing a subdomain that resolves to nothing or shows an error on your VPS. You’ll check DNS records, web server configuration, and local settings, then apply the correct fix. You’ll need SSH access to your VPS, access to your DNS provider’s control panel, and the ability to edit files as root or with sudo.

What You’ll Need

  • SSH client (e.g., Terminal on macOS/Linux, PuTTY on Windows)
  • Credentials for your DNS provider (where your domain’s nameservers are managed)
  • Sudo or root access on the VPS
  • Text editor on the server (nano, vim, or similar)

Step-by-Step

  1. Confirm the subdomain isn’t resolving. On your local machine, run dig subdomain.yourdomain.com (or nslookup subdomain.yourdomain.com). If you get an NXDOMAIN or no answer, the DNS record is missing or incorrect. If you get an IP address but the site still fails, skip to step 4.
  2. Add or correct the DNS A record. Log into your DNS provider’s dashboard, find the DNS records for your domain, and add an A record with the host as subdomain (or subdomain.yourdomain.com depending on provider) and the value as your VPS’s public IPv4 address. If you’re using a wildcard, ensure it’s not conflicting. Save the record.
  3. Wait for DNS propagation. DNS changes can take from a few minutes to 48 hours. Use a tool like dnschecker.org to check global propagation. You can also test with dig @8.8.8.8 subdomain.yourdomain.com to query Google’s DNS directly.
  4. Verify the VPS is reachable. Once DNS resolves, run ping subdomain.yourdomain.com and curl -v http://subdomain.yourdomain.com. If ping fails, check your VPS firewall (ufw or iptables) and ensure port 80 (and 443 for HTTPS) is open. If curl gets a response, proceed to server config.
  5. Check the web server configuration. For Nginx, look at /etc/nginx/sites-available/ and /etc/nginx/sites-enabled/. For Apache, check /etc/apache2/sites-available/ and /etc/apache2/sites-enabled/. Ensure there is a server block or virtual host that includes server_name subdomain.yourdomain.com; (Nginx) or ServerName subdomain.yourdomain.com (Apache). If missing, create one based on an existing config.
  6. Restart the web server. After editing config, test it with nginx -t or apachectl configtest. If the test passes, restart: systemctl restart nginx or systemctl restart apache2.
  7. Set up the subdomain’s content. Ensure the document root (e.g., /var/www/subdomain) exists and contains an index file. If you’re using a reverse proxy (like for a Node.js app), make sure the proxy_pass or ProxyPass directive points to the correct port and that the app is running.
  8. Test locally on the server. Run curl -H "Host: subdomain.yourdomain.com" http://localhost on the VPS. If you get the correct content, the server config is fine. If not, check error logs at /var/log/nginx/error.log or /var/log/apache2/error.log.
  9. Check SSL certificate (if using HTTPS). If you have a wildcard certificate or a cert for the subdomain, ensure it’s installed and that the server block includes the correct SSL paths. If you use Let’s Encrypt, run certbot --nginx -d subdomain.yourdomain.com or the Apache equivalent to obtain a new cert.
  10. Flush local DNS and browser cache. On your local machine, flush DNS (e.g., sudo systemd-resolve --flush-caches on Linux, ipconfig /flushdns on Windows, sudo dscacheutil -flushcache on macOS). Also clear your browser cache or try incognito mode.

Common Mistakes

  • Using the wrong IP address. The A record must point to the VPS’s public IP, not a private IP or the wrong server.
  • Forgetting the trailing dot in DNS. Some providers require a trailing dot in the value field (e.g., yourdomain.com.).
  • Server block not enabled. On Nginx, you need a symlink in sites-enabled pointing to the config in sites-available. On Apache, you may need a2ensite subdomain.conf.
  • Missing document root. The directory specified in the server block must exist and have correct permissions (usually 755 for directories, 644 for files).
  • Firewall blocking ports. Even if the web server runs, the OS firewall might block port 80/443. Check with sudo ufw status and allow if needed.
  • Propagation impatience. Testing too soon after DNS changes can lead to false negatives. Wait at least 10 minutes, or use a DNS checker.

Tips

  • Use a wildcard DNS record (*.yourdomain.com) if you plan to create many subdomains, but be careful: it will also match unintended subdomains.
  • Keep your server config files versioned (e.g., in Git) so you can revert changes easily.
  • Set up a simple test page (like index.html with “Subdomain works!”) to isolate DNS/server issues from application issues.
  • Use curl -I to check response headers; a 200 OK means the server is responding correctly.
  • If using a CDN or reverse proxy, ensure the subdomain is added to those services as well.

Troubleshooting

If the subdomain still doesn’t work after following the steps:

  • Check DNS propagation again. Use dig subdomain.yourdomain.com from multiple locations. If some show the IP and others don’t, wait longer.
  • Verify the server responds to the IP directly. Run curl -v http://YOUR_VPS_IP. If that fails, the web server isn’t running or the firewall is blocking. If it works, the issue is DNS or virtual host configuration.
  • Inspect server logs. Look for errors like “no host matches” or “directory not found” in the error logs. This often points to a misconfigured server block.
  • Test with a different subdomain. Create a temporary subdomain like test.yourdomain.com with the same IP to see if the problem is specific to the original subdomain.
  • Check for conflicting configs. If you have a default server block that catches all requests, it might override your subdomain block. Ensure the subdomain block is more specific or remove the default.
  • Reboot the VPS. Sometimes a simple restart clears stuck services or network issues. Run sudo reboot and test again after it comes back.

Frequently Asked Questions

How long does DNS propagation take?

Typically 5-30 minutes, but can take up to 48 hours in rare cases. Check with a global DNS checker to see if your record is visible.

Can I use a CNAME instead of an A record?

Yes, you can point a subdomain to another domain (e.g., subdomain.yourdomain.com CNAME to yourdomain.com), but only if the target is a hostname, not an IP. For a VPS with a static IP, an A record is more direct and faster.

My subdomain works on some networks but not others. Why?

That’s DNS caching. Some ISPs cache DNS results longer. Wait a bit, or flush your local DNS and try a different network.

I use Cloudflare. Do I need to change anything there?

Yes, if your domain uses Cloudflare, you need to add the subdomain as a DNS record in Cloudflare (with the VPS IP) and ensure the proxy status is set appropriately (grey cloud for testing, orange for proxied). Also, if you have a Cloudflare SSL setting, make sure it matches your server’s setup.

What if I want the subdomain to point to a different port?

You can’t specify a port in DNS. You need to configure the web server to listen on that port and use a reverse proxy if the app runs on a non-standard port. For example, Nginx can proxy port 80 to localhost:3000.

Why does my subdomain show the default VPS page instead of my site?

That means the server is responding but the server block for your subdomain isn’t being used. Check the server_name directive and ensure the config is enabled and the web server restarted.

Related

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.

More cards in this drawer

The whole Numbers and Powers drawer →