Troubleshooting error messages

The LTI process can generate error messages at many steps throughout the process. Most of the time, the error messages you see are due to communication issues with the LMS. This pages contains some tips on how to understand various error messages as well as how to debug/fix some more common issues.

Identifying Error Sources

All error messages that originate from LTIAAS will have the following form:

{
  "status": number, // HTTP status code
  "error": string, // error message from LTIAAS
  "details": {
    "errors": [] // array of generated errors
  }
}

If the error message is not in JSON and not of the form above, the message was generated outside LTIAAS, likely from the LMS.

Common LTIAAS Errors

UNREGISTERED_OR_INACTIVE_PLATFORM

LTIAAS cannot find the LMS that is making the request in the platform registrations table. When an LMS requests access to your tool it sends two key pieces of data: url and clientId. These two data must EXACTLY match the values you entered when you registered the LMS. Some common mistakes are:

1. An extra trailing slash in the url
2. A space or extra character in the clientId (we have seen some LMS admins send clientIds with hidden characters, so it is worth checking values they send you in a tet editor that can identify hidden characters).
3. If you are trying to connect with the Canvas LMS, is probably due to a wrong URL field. Please see our Canvas registration documentation for different urls that the LMS might send.

INACTIVE_SERVICE

Your LTIAAS accoutn does not have the requested service enabled. Please open our account in the LTIAAS Porta to add the service.

SERVICE_NOT_AVAILABLE_FOR_CONTEXT

The LMS doesn't allow the service you are requesting. Even if you have an LTI service enabeld for your account, the LMS can choose to deny the request. This is most likely a setup issue in the LMS side. Please contact the LMS administrator and ask them to anable the service for your tool.

Other Common Errors

{"message":"Forbidden"}

This message is from our Web Application Firewall. If you get this message, the request has been blocked because it has deemed to be unsafe for LTIAAS to process the request. Here's a couple reasons why a request might be blocked:

1. The request is coming from an IP address. LTIAAS requires all requests to come from a full qualified domain name. We block requests originating form a source that is an IP address, i.e. http://127.0.0.1. If you want to test using your local host, please use a dynamic DNS system like ngrok.
2. The request contains query parameters, URLs or body contents that are known to be malicious, like containing SQL queries, attempting to access URLS that are not documented API endpoints, bodies containing code, etc.
3. The request came from an IP address that is on an IP Blacklist.

If you think a request is being blocked in error and should be allowed, please contact support@ltiaas.com.

{"status":400,"error":"Bad Request","details":{"errors":[{"field":"id_token","message":"Missing 'id_token' parameter."}]}}

Error messages like this are basically saying that LTIAAS expected a request to contain certain parameters ('id_token' in this case). If LTIAAS didn't get a property it expected there are two likely causes.

1. If this error was due to an API call by you, like submitting grades, you just need to double-check the request you sent and add the missing property per the API documentation.
2. If the error was seen during the LTI launch process, there are a couple of things that may have caused it:
3. The URLs entered in the LTI registration were incorrect (usually the URLs entered into the LTIAAS Admin Portal). Double check them for spelling errors. Also, if you are trying to connect with the Canvas LMS, please read our note one how the main URL might be different from the other URLs. If a registration is not working, one of the likely causes is an incorrect URL. Please try both https://canvas.instructure.com and https://[YOUR_CANVAS_URL].
4. Instead of sending a valid LTI response, the LMS is sending an HTML formatted error message. To debug these kinds of issues requires some familiarity with the Chrome dev tools to inspect network responses. Please feel free to send LTIAAS a HAR file so we can help you debug this if needed.

The Token can't be used before DATE

This is uncommon, but it does happen form time ot time. If you see a message like this, it is usually telling you that the LMS thinks that an LTI token generated by LTIAAS was generated in the future. Our servers are fast, but not that fast. This error is because the LMS's local time is not in sync with global NTP time. The LMS local server time must be within a couple minutes of the time.google.com NTP servers for OAuth tokens to be validated correctly. Please ask the server administrator of the LMS to validate and update the LMS server's local time.

Third Party Cookies Are Being Blocked

Many web browsers are starting to block third party-cookies. This prevents iFrames from creating user session Cookies. Please see our guide about how to manage third-party cookies with LTI.

Common Canvas Errors

Canvas is surprisingly challenging to get LTI working in, especially if you are self-hosting your own Canvas instance for development.

Authlogic Validation Error: You did not provide any details for authentication.

Well, this isn't an error you would see in a web browser, but you will see it in the Canvas server logs. This kind of issues shows up when Canvas isn't creating secure user sessions. Another way his shows up is be consistently redirecting the user back to the Canvas login screen even though the user had already logged in. You probably need to modify this file on the Canvas server:

Copy config/session_store.yml.example to config/session_store.yml and apply the following patch to set the "secure" property to "true". Explained here: https://github.com/instructure/canvas-lms/issues/1900

--- config/session_store.yml.example    2023-09-18 11:29:04
+++ config/session_store.yml    2023-09-18 14:02:25
@@ -1,7 +1,7 @@
 development:
   session_store: encrypted_cookie_store
   expire_after: 86400 # 1 day in seconds
-  # secure: true
+  secure: true
 
 production:
   session_store: encrypted_cookie_store