Troubleshooting

Overview

If any problems arise or if you are unable to access FusionAuth, consult the FusionAuth log files. In most cases API errors will be written out to the fusionauth-app.log file.

If you need further assistance, please ask a question in the FusionAuth forum or open an issue on Github if you have additional questions. If you have a licensed edition you may open a support request from your FusionAuth Account page.

Logs

System log UI

The system logs may be reviewed in the FusionAuth admin UI by navigating to System → Logs. This feature was added in version 1.16.0. This UI will only render logs for systems that write their logs out to disk. Deployments which write logs to STDOUT, such is the case with Docker, will not be able to review logs through this interface.

The system log UI organizes and renders the most recent 64KB of all logs for all nodes in the deployment. If you need the entire log, use the download action in the upper-right hand corner of UI to download a zip of all logs.

System Logs - Single Node System Logs - Multiple Nodes

Filesystem logs

Alternatively, the logs may be accessed directly. The following are the default locations for each of the FusionAuth log files. You may or may not have all of the FusionAuth services installed for your system, so you may not have all of the following logs on your server.

Linux and macOS
/usr/local/fusionauth/logs/fusionauth-app.log
/usr/local/fusionauth/logs/fusionauth-search.log

These paths assume the suggested product location of \fusionauth. This path may be different on your system depending on where you unpacked the zip files.

Windows
\fusionauth\logs\fusionauth-app.log
\fusionauth\logs\fusionauth-search.log

Note that if you started Windows via Fast Path, the fusionauth-app.log file will not be created. Instead the services are running interactively and all logging is written to to stdout.

Event Log

Available since 1.6.0

The event log is a FusionAuth message store designed to capture different types of events that may be necessary to communicate to a FusionAuth developer or admin user.

The event log may contain helpful details to indicate the cause of the failure, or a failure condition you need to be aware of in FusionAuth. See System → Event Log.

While not limited to, generally speaking the event log will contain events or errors related to external systems or asynchronous issues that are difficult to communicate to the API caller or the FusionAuth admin at runtime. While not intended to be an exhaustive list, examples of these types of errors are:

  • SMTP connection issues

  • Lambda invocation errors

  • External identity provider failures or configuration issues

  • Failure to deliver a webhook event

Troubleshooting email

FusionAuth sends a lot of email, for forgotten passwords, passwordless login and other features.

Troubleshooting email delivery is difficult. There are many factors affecting it. However, there are steps you can take to narrow down the problem.

Send a test email

The Send Test Email button has been available since 1.16.0

The first step is to ensure that you can send a test email. Navigate to Tenants → Your Tenant → Edit → Email and send a test email. If it is received, FusionAuth can send emails via SMTP.

Sending a test email

If sending a test email fails, a tool such as SWAKS can help debug SMTP issues. Using this tool removes FusionAuth from the equation.

Further investigation

If the test email succeeds, but you aren’t receiving other emails, investigate further by following these steps:

  • Send emails to different addresses at different providers and check the spam folder.

  • Make sure that you are firing the event that you expect to send email correctly. For instance, if you are looking for email verification of users, make sure that is enabled.

  • Test with a different FusionAuth function. Sending a password reset email is easy to do from the user details screen.

  • Make sure the email template is correct, or use a default template.

SMTP logging

If you would like to see verbose SMTP logging, follow these steps:

  1. Enable debugging by navigating to Tenants → Your Tenant → Edit → Advanced → SMTP Settings → Additional properties and add mail.debug=true.

  2. Save the tenant.

  3. Send an email.

  4. View the system logs by navigating to System → Logs.

  5. Select fusionauth-app.log and you will see verbose SMTP output.

Doing this logs the full SMTP conversation, which can be verbose. You should remove this setting when you have finished troubleshooting.

Common Errors

Be sure to review the Common Errors page to see if there are any fixes for any issues you encounter.