.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
.svg)
The full message is "SMTP not configured, check your grafana.ini config file's [smtp] section". The first time I hit it I spent forty minutes rewriting the host and the port, and both had been correct the whole time. The message names the right file and points you at the wrong line inside it.
What the error means, from the Grafana source
The string is defined once, in pkg/services/notifications/models.go:
var ErrSmtpNotEnabled = errors.New("SMTP not configured, check your grafana.ini config file's [smtp] section")And it is returned from exactly one place, a single guard in pkg/services/notifications/mailer.go:
if !ns.Cfg.Smtp.Enabled {
return nil, ErrSmtpNotEnabled
}That's the whole story. The message means one thing: Smtp.Enabled is false in the configuration the running process holds in memory. Grafana returns it before it resolves a hostname and long before it opens a socket. So a wrong host cannot produce it. Neither can a bad password, a certificate problem, a blocked port or a relay that rejects your sender. Those all happen later and produce different errors from the dialer, with words like dial tcp or x509 in them.
Checking your SMTP host and port cannot fix it. The question is why enabled is false when you are sure you set it to true.
Check the config the running process loaded
Settle this first, because it splits the problem in half. Grafana exposes its effective configuration, after every override layer has been applied, to a server admin:
curl -s -u admin:yourpassword http://localhost:3000/api/admin/settings | jq .smtpThat endpoint only accepts basic auth and only for a Grafana server administrator, and it redacts the password to a run of asterisks. The Grafana admin HTTP API reference documents the response shape. Same view in the browser under Administration, then General, then Settings, which is /admin/settings.
If enabled comes back "false" there, the file you edited is not reaching the process, and one of the seven reasons below is why. If it comes back "true", you are past this error entirely and whatever you're seeing now is a different failure, covered at the end.
No admin password to hand? Fall back to the file plus the startup log:
sudo grep -n -A 14 '^\[smtp\]' /etc/grafana/grafana.ini
sudo journalctl -u grafana-server -n 60 --no-pagerSeven reasons enabled is still false
The line is still commented out
This is the one, by a wide margin. The /etc/grafana/grafana.ini that ships with the package is a copy of conf/sample.ini, and every line in sample.ini starts with a semicolon. A leading semicolon is an INI comment. You open the file, find the [smtp] block sitting there looking configured, change false to true, and save a line that reads ;enabled = true.
That convention exists because sample.ini is documentation and configuration at the same time, so every key is present with its shipped default visible next to it. As a way to write a config file it is a good idea. It also produces this exact bug somewhere in the world about once a week.
Run the grep above and look at the left edge of every line. Strip the semicolon from the keys you're setting, and from the [smtp] header itself. A section header that's still a comment puts every key under it into whatever section came before.
You edited a different file from the one Grafana reads
Grafana reads one custom config file and the path depends on the install. On deb or rpm it's /etc/grafana/grafana.ini. On a tarball install it's conf/custom.ini, which you create yourself, and editing conf/defaults.ini instead is a common wrong turn: the docs say "Don't change this file", and it's overwritten on upgrade anyway. Homebrew puts it under /opt/homebrew/etc/grafana/ or /usr/local/etc/grafana/ depending on the CPU. On Windows you copy conf\sample.ini to conf\custom.ini.
Stop guessing and ask the process which file it was told to use:
ps -eo args | grep '[g]rafana' | head -1The --config= argument in that output is the only file that matters. Every install layout is listed in where to set up Grafana SMTP settings, along with the full key reference. On Windows the separator is a backslash.
The process never sees that file
Containers and Kubernetes both do this to people. If you edited /etc/grafana/grafana.ini on the host and never mounted it into the container, the container is still using its own copy, which is sample.ini with everything commented out. Check inside:
docker exec grafana grep -A 3 '^\[smtp\]' /etc/grafana/grafana.iniUnder Helm the config comes from the grafana.ini key in your values file, rendered into a ConfigMap. Editing the file inside a running pod works until the pod restarts, at which point the chart writes its own version back. Fix it in values.yaml and upgrade the release. Environment variables are the cleaner route in both cases, and the Grafana Docker Compose setup shows the shape they take. The same keys go in a pod spec's env block.
Grafana was not restarted
Nothing watches the file. Grafana parses it when the process starts and never looks again.
sudo systemctl restart grafana-serverThe systemd unit kept its old name even though the CLI binary is now the two-word grafana server, so grafana-server is right here. In Docker, note that changing an environment variable needs the container recreated, not restarted: docker compose up -d --force-recreate grafana. A plain docker restart reuses the existing environment and you'll swear the variable did nothing.
An environment variable is overriding the file
Environment variables outrank your config file. That is the whole mechanism here, and it is why a stale GF_SMTP_ENABLED=false sitting in a systemd drop-in or a compose file quietly beats the grafana.ini you just fixed. Nothing warns you.
sudo systemctl show grafana-server -p Environment -p EnvironmentFiles
docker exec grafana env | grep GF_SMTPThe full precedence chain, all five layers of it, is written out on the Grafana page for configuring Grafana. Reading it once removes most of the config surprises you will ever have with this software.
The section header is misspelled
[smpt] is easy to type and impossible to see. Putting enabled = true above the header does the same damage, since the key silently joins the preceding section. List the headers and read them:
sudo grep -n '^\[' /etc/grafana/grafana.iniYou want exactly one [smtp]. If a second one appears later in the file, left behind from an earlier attempt, the later block wins and it is usually the empty one. I have never worked out if that comes from the INI library or from Grafana's own loading, and it has never mattered enough to go and look.
The value has quotes or trailing whitespace
Type the value bare: enabled = true, nothing after it.
A line pasted out of a forum thread can carry a non-breaking space or a trailing tab that no editor shows you. Make it visible:
sudo sed -n '/^\[smtp\]/,/^\[/p' /etc/grafana/grafana.ini | cat -A | head -20cat -A marks line ends with $ and tabs with ^I, so enabled = true$ is clean and enabled = true^I$ is your problem. Retype the line rather than trying to delete the invisible character.
Errors that appear after enabled = true
Once the flag is genuinely true, sending gets as far as the network and the errors change completely. None of the messages below is this article's error.
| Message | What it means |
|---|---|
dial tcp ...: i/o timeout | Nothing is listening or something is filtering. A localhost:25 or :25 host is the usual culprit, since outbound 25 is shut by default on most hosting networks. |
x509: certificate signed by unknown authority | No CA bundle where Grafana is running. Common in minimal containers missing ca-certificates. |
x509: certificate is valid for a.example.com, not b.example.com | The hostname in host doesn't match the relay's certificate. Use the name the provider documents, not an IP. |
535 5.7.8 Username and Password not accepted | Credentials rejected. On Gmail this usually means a regular password where an app password is required. |
gomail: invalid address | An address failed to parse. Check from_address for a stray display name or angle brackets, and check the recipient list on the contact point. |
invalid email address for SMTP from_address config | Raised at startup by the notifications service when from_address isn't a valid address. It appears in the log, not in the UI. |
Grep the log for that last one even when mail looks fine, because it fires during service initialisation and scrolls away fast. Where the log lives differs between a package install and a container, and where Grafana logs live covers both layouts. It is a five second check either way.
Test the connection without Grafana
When the error is a network or credential one, take Grafana out of the picture. Two commands settle it.
openssl s_client -starttls smtp -crlf -connect smtp.example.com:587A hang means egress filtering or a firewall. A printed certificate chain and a 250 banner means the path is open and TLS negotiates, so the problem is authentication or sender identity. For a full send including the login:
sudo apt-get install -y swaks
swaks --to [email protected] --from [email protected] \
--server smtp.example.com:587 --tls \
--auth LOGIN --auth-user [email protected]swaks prompts for the password and prints the entire SMTP conversation, so you see the exact response code the relay gives. If swaks delivers a message and Grafana still won't, the difference is in the config values. The Grafana troubleshooting docs and the roundup of common Grafana errors cover what is left of the list. With enabled true and a test send landing, the next thing to build is the contact point and the rules behind it, which is setting up email alerts in Grafana.
