diff --git a/doc/settings/grafana.md b/doc/settings/grafana.md
index dac9fdcf4d51bc0dce3fb74adc3c948b007ec2b4_ZG9jL3NldHRpbmdzL2dyYWZhbmEubWQ=..07da94c8927d2fb52ada346f857cefc6e16bca77_ZG9jL3NldHRpbmdzL2dyYWZhbmEubWQ= 100644
--- a/doc/settings/grafana.md
+++ b/doc/settings/grafana.md
@@ -184,3 +184,23 @@
 ```
 
 For more information on Grafana's SMTP configuration see Grafana's [documentation](https://grafana.com/docs/grafana/latest/administration/configuration/#smtp).
+
+## Troubleshooting
+
+### X.509: certificate signed by unknown authority
+
+When using a self-signed SSL certificate for GitLab, you may get the following error in the UI:
+
+```plaintext
+login.OAuthLogin(NewTransportWithCode)
+
+Check the Grafana server logs for the detailed error message.
+```
+
+The error reported in the Grafana logs at `/var/log/gitlab/grafana/current` can be:
+
+```plaintext
+lvl=eror msg=login.OAuthLogin(NewTransportWithCode) logger=context userId=0 orgId=0 uname= error="Post \"https://gitlab.example.com/oauth/token\": x509: certificate signed by unknown authority"
+```
+
+In this case, you must [install the self-signed GitLab certificate as trusted](ssl.md#install-custom-public-certificates).