The Vikunja Email Pitfall: Why CLI Password Resets Claim Success But Fail (And How to Fix It)

July 19, 2026

Vikunja is a fantastic self-hosted to-do and task management app. However, if you are setting up email notifications or password recovery, you might run into a highly confusing quirk: Your email configuration works perfectly for test emails, claims success on CLI password resets, but never actually sends the reset mail unless you use the web interface.

If you are currently looking at your mail server logs and seeing absolute silence during a CLI reset, here is exactly what is happening and how to deal with it. Vikunja supports a variety of environment variables to hook up your mail server. Depending on your infrastructure, you usually choose one of two main approaches:

The Internal Plaintext Relay (Port 25)

If your mail server (like Postfix) runs in the same local network or on the same host, you often don’t need authentication or TLS encryption. To force a standard internal plaintext connection, use this strict setup:
VIKUNJA_MAILER_ENABLED: "true" VIKUNJA_MAILER_HOST: 10.x.x.x # Your mailserver IP VIKUNJA_MAILER_PORT: "25" VIKUNJA_MAILER_AUTHTYPE: none VIKUNJA_MAILER_SKIPTLSVERIFY: "true" VIKUNJA_MAILER_FROMEMAIL: [email protected]

Authenticated SMTP (Port 587 / 465)

If you are using an external provider (like Mailgun, SendGrid, or Gmail), you will need to provide credentials:
VIKUNJA_MAILER_ENABLED: "true" VIKUNJA_MAILER_HOST: smtp.provider.com VIKUNJA_MAILER_PORT: "587" VIKUNJA_MAILER_USERNAME: your_username VIKUNJA_MAILER_PASSWORD: your_password VIKUNJA_MAILER_FROMEMAIL: [email protected]

Crucial Side Note: Make sure your VIKUNJA_SERVICE_PUBLICURL does not have a trailing slash (e.g., use [https://vikunja.domain.com](https://vikunja.domain.com), NOT [https://vikunja.domain.com/](https://vikunja.domain.com/)). A trailing slash breaks the password link generation, causing resets to fail silently – at least in my setup/version.

Verification via the testmail Command

Before testing password resets, you should verify that Vikunja can actually talk to your mail server. Vikunja has a built-in CLI command specifically for this.Run it inside your Docker environment like this:

docker compose exec -it vikunja /app/vikunja/vikunja testmail [email protected]

Why this works: The testmail command sends the email immediately. If your configuration is correct and the mail server is reachable, the mail will accept the connection and the email will arrive in your inbox right away.

The Quirk: user reset-password via CLI Claims Success But Does Nothing

Once your testmail arrives safely, you would expect the password reset command to work the same way. You run:

docker compose exec -it vikunja /app/vikunja/vikunja user reset-password username

The terminal output proudly states:

Password reset email sent successfully.

However, looking at your mail server logs, there is absolute silence. No connection attempt, no traffic, nothing. The CLI command closes immediately after printing the message, but no bytes ever leave the container.

The Solution: Trigger it via the Homepage

To successfully trigger a password reset email, do not use the CLI. Instead, use the active web application:

Go to your Vikunja login page (e.g., in an Incognito window).
Click “Forgot Password”.
Enter the username or email address.

When triggered via the web interface, the mail server logs will immediately show the connection attempt, and the password reset link will be sent successfully.

Troubleshooting Checklist

If the testmail works but the web UI reset still doesn’t send anything, ensure that the affected user actually has a valid email address stored in the database. If they signed up without one, you can update it via the CLI first:

docker compose exec -it vikunja /app/vikunja/vikunja user update --email [email protected] username

In HowTo, Linux | No Comments

No Comments yet »

RSS feed for comments on this post. TrackBack URI

The Vikunja Email Pitfall: Why CLI Password Resets Claim Success But Fail (And How to Fix It)

No Comments yet »

Leave a comment