Troubleshooting Email Errors
Users aren't receiving notifications
Note: the email account associated with standard notifications is NOT configured under "Ticketing". It is located at: Configure Gemini...System...Email & Alerts.
- The System SMTP is responsible for Resource Assignment, Follower, and Workspace notifications. Save the configuration of the SMTP definition and Gemini will immediately use it to send you a test message. Any errors in this test will be thrown to the page, so this should be your first step unless your problem is linked to specific users only.
- If saving the configuration gives you errors you don't understand, look in the System Log for a more comprehensive explanation. If you still don't understand the error(s) send a screenshot to Countersoft support.
- If your SMTP is working, and you have problems with just one or more users:
- Make sure you are using SSL, and ideally TLS 1.2 as the protocol. If you have TLS Auto it should use TLS 1.2, but it won't hurt to be specific if you are having problems.
- Check the users in question should be receiving the specific emails in the first place. Some users expect to receive notifications because there are changes to things in their Workspace(s), who turn out not to be Followers or Resources on the item(s) in question.
- If they are outside your network, ask the user(s) to check with their IT function that emails from your Gemini Mail Account are not being blocked. You may be able to send them an email from your email client, but that is not an email from Gemini.
- Check that the email address against their Gemini user record is valid, and their User Account in Gemini is not Locked or Disabled.
- Check that email is enabled on the alerts tab in their user profile(s)
Errors using/configuring Microsoft OAuth
If you are using Microsoft OAuth and you get an error, please search for the error online. Most Azure error messages give you accurate hyperlinks to documentation that can help you resolve the problem.
Please note the following:
- The most common configuration error is that when redirected to the Microsoft login to confirm OAuth credentials, users login as themselves or an admin instead of the email account that is being configured for Gemini to access. You must login as the email account e.g. email@example.com with the password for that email account.
- When setting up SMTP, admins sometimes forget to enable SMTP on the email account in the Office365 Portal.
- Do not reconfigure an existing mailbox for OAuth and leave the password in it. Gemini has no logic for what to do in that instance - it passes a password if one exists, and MS returns an error because it has no logic for what to do with it either. OAuth uses tokens, not passwords, but if one exists on your Gemini Mailbox, when you select OAuth as the connection method, Gemini will (correctly) hide the password field but keep its value. To avoid these kinds of cross-configuration errors, we recommend you disable the Queue for your current mailbox and create a new Queue and Mailbox for OAuth. The overhead in time is tiny and the config is clean.
- You cannot use POP with OAuth, you can only use IMAP and Exchange Web Services. If you use IMAP you MUST specify the SSL Protocol as TLS 1.2/TLS Auto, since TLS 1.1 is deprecated. EWS will automatically use TLS 1.2.
- You can only use http with localhost for testing e.g. http://localhost/... For any other site you MUST use "https", and a self-signed SSL certificate may not work.
- You can configure an App Registration in Azure for a Gemini site that is not publicly available.
- You cannot use a virtual email account (usually a shared account) as a Gemini Mailbox. You MUST use a standard, paid email account. We strongly recommend that any mailbox Gemini processes is not shared with any other application or user.
- If you reply to email from Gemini (Breeze Reply), use the same email account for the ticketing mailbox as its associated SMTP. If you don't do this, messages and replies cannot be threaded.
- OAuth is not the same as Microsoft Graph though there is obvious overlap under the hood. Some Gemini Administrators have wasted a lot of time looking at Graph documentation and settings. Forget Graph, just configure OAuth exactly as specified in the online documentation.
Token/Secret expiry using Microsoft O365
Tokens and Secrets do expire. At the time of writing, Microsoft does not allow tokens/secrets to be used indefinitely. That said, if you get a message saying that a token has expired because it hasn't been used in 90 days, and you are not on Gemini 7.3 or above, then please upgrade as this is a known problem in early G7. Gemini 7.3 is Gemini 7.2 compiled against a later version of Microsoft's Client Identity Library to address this specific error. There are no 7.3 Release Notes as it is a patch release of 7.2 with no functionality or database changes.
If you are on 7.3 or above and you get a token/secret expiry message, please check the expiry date of your Client Secret in Azure before you decide it is a bug with either Gemini or Azure.
Unable to get token silently
You get this error message when Gemini gets a generic error from Azure. At the time of writing there appears to be no way around this problem except to re-input a client secret and re-authenticate with Azure.
URI Error mismatch using MS OAuth
This can be a difficult MS OAuth error message to untangle. If it is correct and you do have the wrong URI in Azure, correct the Azure setting remembering that the URI is cAsE sensitive. However, Azure is capable of reporting that http://yoursite is an invalid redirect URI when you have connected from https AND you have no such http://yoursite setting in Azure. It appears that the error comes from Azure communicating with IIS and discovering that your Gemini site is accessible with http because you have no http to https redirect and your IIS configuration does not state "Require SSL". Your site MUST NOT be http accessible in any way.
Microsoft O365 SMTP config just says "OAuth connection unsuccessful"
Check that your redirect URI in Azure exactly matches the case of your website. "Gemini" and "gemini" are not equivalent to Azure, it will just assume it has no redirect URI that matches your site.
Save the configuration from a browser in Incognito mode to make sure there is caching or cookies affecting the authentication process with Microsoft.
Double check the following match exactly:
- You've picked the right Server and Port
- You've got an exact match on these Scopes
- You've enabled TLS 1.2 as shown below. TLS Auto should pick the correct level after negotiating with the host, but this can go wrong, so if you have a problem be explicit.
If such messages persist, particularly if OAuth suddenly stops working so you know you have a valid configuration, input an invalid Client Secret. This challenge of testing its security seems to wake Azure up. Once you get the Microsoft login prompt, go back to Gemini, input the valid Client Secret, and the next time you authenticate with Azure it will work if your configuration is valid.
Error - string exceeds length of mapping parameter
We are still investigating this error as it is very hard to reproduce. Emails that fail at customer sites do not fail on Countersoft's test instances. It could be the result of new logic in Office 365 that results in a massively long set of referrers in the header. GeminAI currently has this logged as possibly a 'feature' of O365/Exchange that the MailBee component used by Gemini has not caught up with. At this time, the recommended solution is to move all unprocessed emails out of the inbox and move them back in batches in a binary chop method to quickly identify and remove the problem email.
Email processing is running slowly
If your email processing is taking a lot of time, look at the number of emails in the inbox. If you don't enable the checkbox "Limit to Unread" in your mailbox(es) then Gemini must read all messages to determine what it has processed, because another application or a user could have marked the email as read. Large numbers of read emails in a mailbox that does not have the "Limit to Unread" flag is a direct cause of sub-optimal performance. If your mailbox isn't large, please check the System Log to see if you are getting errors in processing (such as the known error above) or timeout errors that indicate something else is slowing down the system.
Email processing is fast, but like all background processes it consumes resources. Gemini will not allow overlapping instances of email processing but as a rule of thumb, email (and SLA) processing should not run at shorter than 2-minute intervals to give the system time to completely process one set of emails/SLA rules before looking for the next set.
System reports aborted connections
The system isn't lying, the remote host aborted the connection. Networks fail. You need to get a sysadmin/network engineer/IT to look into the connection between your Gemini application server and whatever system it is you are trying to reach.
Microsoft OAuth Unauthorised error
Please check your OAuth configuration. You should save the mailbox/SMTP definition to see if it is still valid. On saving, Gemini will test the given configuration immediately, so any errors or genuine misconfiguration (say an expired password/misspelt mailbox) can be caught by doing this one simple thing.
Gmail Unauthorised error
Like Microsoft, Google no longer supports Basic (Username/Password) Authentication. You can set up OAuth for GMail or take the easier option of creating an App Password for GMail, which will work just like a normal password in that you enter it into the password field in your mailbox/SMTP configuration alongside the email address of your mailbox. Please note that in order to set up an App Password in GMail, your email account MUST be configured for 2FA. You will also get unauthorised errors if your password has expired.
The URL of our outbound emails is wrong
In Gemini, there are 3 places where a URL can be specified.
- Web.config has <add key="gemini.url" value=""/> in the appSettings section. This can be empty.
- In the table gemini_applicationsettings where SettingValue is 'URL'.
- In the table gemini_applicationsettings where SettingValue is 'FullGeminiURL'.
If you make sure that any value supplied is consistent (and consistent with IIS), you will not have a problem.
Customers are seeing comments from internal users on their emails
This can happen if your email alert template pulls all comments or the last comment. The functionality in Gemini to avoid this is to set Visibility of internal comments to the appropriate user Group that excludes customers.
I am getting errors with the Close Ticket Template
Please make sure that you have specified a valid Status for every Project Template on the template list or you will get a runtime error when Gemini tries to load them.