Troubleshooting

Owned by Rod Widdowson
Last updated: Nov 24, 2021
3 min read

Everyone's life is easier if you try to help yourself.  If you can help yourself then you have learnt and developed, and other's have been save what is often reiteration. 

Tactics

Logging

You have logs, please use them.  The Logging topic contains an overview of the SP's logging features.

It is not reasonable behavior to ask support questions unless you've looked at your logs first. Often this will require both sets of logs (SP and IdP), but the SP log is usually sufficient to at least identify who's at fault.

It's also not reasonable to "look at the log" by dumping it out into an email and expecting others to read them for you. The logs are there so you can solve problems on your own. When you don't understand something in the log, you should first search the wiki and the mailing list archive to see if the message has an explanation.

If that doesn't work, ask, but in doing so you should be prepared to help the product by explaining why you didn't understand the log message that should have helped to solve the problem. That way we can improve the log messages for future releases.

Crashes

They happen. Older Shibboleth versions had overly aggressive exception handling that traps errors but often destabilizes the software or your web server, while hiding the cause of the crash so it can't be fixed. This has been changed, but will probably result in more crashes as bugs are hit.

If you want to restore the older aggressive exception handling, you can add the attribute catchAll="true" to the <InProcess> or <OutOfProcess> configuration elements, as required.



In general, don't bother just asking "why is this crashing?". We don't know. If we did, we'd have fixed it. What you have to do, generally, is to get a stack trace and/or provide detailed log files (with significant categories on DEBUG) to help identify the cause of the crash. This is particularly essential if the crash appears to be random, as in cases where the software will run for a while without any problems and then fail.

If a crash is reproducible, it may be enough to provide a trace of the XML or other information that leads to a crash. But when it's not, you MUST figure out how to get a stack trace out or there isn't going to be any way to research the problem.

Consortium Members can ask via their support channel.

  • If you don't know whether you are consortium member ask.  

  • If you are a If you want to become a member ask

  • If you want to support Shibboleth by becoming a member.

When asking for help on the mailing list...

Always start by checking your logs and thinking about the problem in the context of how the software works.

If that doesn't help, always check the the common errors page for a better explanation of the log or error message, and failing that, try the mailing list archive.

If you need further help, send an email (starting a new thread) to the mailing list indicating which version of the SP you are running, the web server your are using, and a small part of your log files.

You should not email a multi-megabyte log file to the email list, and you should also not just post your entire configuration, metadata, etc.

Specific Guides