diff --git a/docs/en/security/troubleshooting.asciidoc b/docs/en/security/troubleshooting.asciidoc
index d4860c56fd3..64ca7522039 100644
--- a/docs/en/security/troubleshooting.asciidoc
+++ b/docs/en/security/troubleshooting.asciidoc
@@ -12,6 +12,7 @@ answers for frequently asked questions.
 * <<trb-security-sslhandshake>>
 * <<trb-security-ssl>>
 * <<trb-security-internalserver>>
+* <<trb-security-setup>>
 
 
 To get help, see <<xpack-help>>.
@@ -327,3 +328,86 @@ Internal Server Error.
 If the Security plugin is enabled in {es} but disabled in {kib}, you must
 still set `elasticsearch.username` and `elasticsearch.password` in `kibana.yml`.
 Otherwise, {kib} cannot connect to {es}.
+
+
+[[trb-security-setup]]
+=== Setup-passwords command fails due to connection failure
+
+The {ref}/setup-passwords.html[setup-passwords command] sets passwords for
+the built-in users by sending user management API requests. If your cluster uses
+SSL/TLS for the HTTP (REST) interface, the command attempts to establish a
+connection with the HTTPS protocol. If the connection attempt fails, the
+command fails.
+
+*Symptoms:*
+
+. {es} is running HTTPS, but the command fails to detect it and returns the
+following errors:
++
+--
+[source, shell]
+------------------------------------------
+Cannot connect to elasticsearch node.
+java.net.SocketException: Unexpected end of file from server
+...
+ERROR: Failed to connect to elasticsearch at
+http://127.0.0.1:9200/_xpack/security/_authenticate?pretty.
+Is the URL correct and elasticsearch running?
+------------------------------------------
+--
+
+. SSL/TLS is configured, but trust cannot be established. The command returns
+the following errors:
++
+--
+[source, shell]
+------------------------------------------
+SSL connection to
+https://127.0.0.1:9200/_xpack/security/_authenticate?pretty
+failed: sun.security.validator.ValidatorException:
+PKIX path building failed:
+sun.security.provider.certpath.SunCertPathBuilderException:
+unable to find valid certification path to requested target
+Please check the elasticsearch SSL settings under
+xpack.security.http.ssl.
+...
+ERROR: Failed to establish SSL connection to elasticsearch at
+https://127.0.0.1:9200/_xpack/security/_authenticate?pretty.
+------------------------------------------
+--
+
+. The command fails because hostname verification fails, which results in the
+following errors:
++
+--
+[source, shell]
+------------------------------------------
+SSL connection to
+https://idp.localhost.test:9200/_xpack/security/_authenticate?pretty
+failed: java.security.cert.CertificateException:
+No subject alternative DNS name matching
+elasticsearch.example.com found.
+Please check the elasticsearch SSL settings under
+xpack.security.http.ssl.
+...
+ERROR: Failed to establish SSL connection to elasticsearch at
+https://elasticsearch.example.com:9200/_xpack/security/_authenticate?pretty.
+------------------------------------------
+--
+
+*Resolution:*
+
+. If your cluster uses TLS/SSL for the HTTP interface but the `setup-passwords`
+command attempts to establish a non-secure connection, use the `--url` command
+option to explicitly specify an HTTPS URL.  Alternatively, set the
+`xpack.security.http.ssl.enabled` setting to `true`.
+
+. If the command does not trust the {es} server, verify that you configured the
+`xpack.security.http.ssl.certificate_authorities` setting or the
+`xpack.security.http.ssl.truststore.path` setting.
+
+. If hostname verification fails, you can disable this verification by setting
+`xpack.security.http.ssl.verification_mode` to `certificate`.
+
+For more information about these settings, see
+{ref}/security-settings.html[Security Settings in {es}].