Understanding Why the Clipboard API Fails on dev.local Mapped in /etc/hosts (HTTP) and Succeeds on local host
Understanding Why
When developing web applications locally, developers sometimes add a custom domain (e.g., dev.local) to their /etc/hosts file, mapping it to 127.0.0.1 for convenience. However, you may encounter the following error in Chrome (tested with Version 131.0.6778.205 (Official Build)):
Uncaught Error: Clipboard API not supported in this browser.
At first glance, it might look like the browser lacks Clipboard API support entirely. In reality, Chrome is blocking Clipboard API access because the page is being served over an unsecured origin (HTTP on a custom domain). Modern browsers impose strict security requirements on various powerful APIs—such as the Clipboard API—to protect users. This means certain features only become available if:
- The site is served over HTTPS (using a valid TLS certificate), or
- The site is running on localhost, which is treated by most browsers as a secure context by default.
Why localhost Works but dev.local Does Not
- Localhost: Browsers recognize localhost and treat it as a secure origin, even without HTTPS. As a result, the Clipboard API is enabled.
- dev.local: When mapped via /etc/hosts for HTTP traffic, dev.local does not qualify as a secure origin. Hence, Chrome disables the Clipboard API, leading to the “Clipboard API not supported” error.
How to Fix This Issue
Use HTTPS for dev.local
- Set up an HTTPS certificate for your custom domain. Self-signed certificates can work for development, though you may need to manually trust them in your browser.
- Once your domain is recognized as secure, the Clipboard API should function normally.
Continue Using localhost
- If HTTPS setup is not feasible right away, use localhost to maintain uninterrupted access to secure APIs like the Clipboard API.
Top comments (2)
Great