Skip to content

Latest commit

 

History

History
58 lines (45 loc) · 2.44 KB

troubleshooting.md

File metadata and controls

58 lines (45 loc) · 2.44 KB
Raw

Troubleshooting

Purpose

This document describes basic troubleshooting steps for ma1sd.

Logs

Locations

ma1sd logs to STDOUT (Standard Output) and STDERR (Standard Error) only, which gets redirected to log file(s) depending on your system.

If you use the Debian package, this goes to syslog.
If you use the Docker image, this goes to the container logs.

For any other platform, please refer to your package maintainer.

Increase verbosity

To increase log verbosity and better track issues, the following means are available:

  • Add the -v command line parameter
  • Use the environment variable and value MA1SD_LOG_LEVEL=debug

Reading them

Before reporting an issue, it is important to produce clean and complete logs so they can be understood.

It is usually useless to try to troubleshoot an issue based on a single log line. Any action or API request in ma1sd would trigger more than one log lines, and those would be considered necessary context to understand what happened.

You may also find things called stacktraces. Those are important to pin-point bugs and the likes and should always be included in any report. They also tend to be very specific about the issue at hand.

Example of a stacktrace:

Exception in thread "main" java.lang.NullPointerException
        at com.example.myproject.Book.getTitle(Book.java:16)
        at com.example.myproject.Author.getBookTitles(Author.java:25)
        at com.example.myproject.Bootstrap.main(Bootstrap.java:14)

Common issues

Internal Server Error

Contact your administrator with reference Transaction #123456789

This is a generic message produced in case of an unknown error. The transaction reference allows to easily find the location in the logs to look for an error.

IMPORTANT: That line alone does not tell you anything about the error. You'll need the log lines before and after, usually including a stacktrace, to know what happened. Please take the time to read the surround output to get context about the issue at hand.

Submit an issue

In case the logs do not allow you to understand the issue at hand, please submit clean and complete logs as explained here in a new issue on the repository, or get in touch.