Your LTI tool isn't launching. The student clicks the link in the LMS and gets an error, a blank screen, or gets redirected back to the LMS. Here's how to find the problem fast.
LTI launch failures almost always fall into one of five categories: configuration errors, OIDC flow problems, token validation failures, state issues, or platform-specific quirks. Work through this checklist in order.
Step 1 - Check the basics first
Before anything else, confirm these:
- Is your tool registered correctly in the LMS? Every LMS has its own external tool registration flow. Canvas, Moodle, Blackboard, and Brightspace all configure differently. Check that the client ID, deployment ID, and launch URL are entered exactly as your tool expects them.
- Is your tool's public key or JWKS URL accessible? LTI 1.3 uses public key cryptography. The LMS needs to fetch your JWKS (JSON Web Key Set) to verify messages. If your JWKS endpoint returns an error or is blocked by a firewall, launches will fail silently.
- Is your launch URL correct and publicly accessible? Test it directly in a browser. If it returns a 404 or redirects unexpectedly without LTI context, the URL is wrong.
Step 2 - Trace the OIDC flow
LTI 1.3 launches use an OpenID Connect third-party initiated login flow. It involves multiple redirects and is the most common source of confusion.
The flow works like this: the LMS sends an OIDC login initiation request to your tool, your tool responds with a redirect back to the LMS authorization endpoint, the LMS then sends the actual LTI message (id_token) to your tool's redirect URI.
Where it commonly breaks:
Login initiation URL mismatch - the URL you registered for OIDC login in the LMS must exactly match what your tool expects. A trailing slash difference or http vs https can break it.
Redirect URI mismatch - same issue. The redirect URI registered with the LMS must exactly match what your tool sends in the OIDC request.
State parameter not preserved - your tool generates a state parameter at login initiation and expects it back after the LMS redirect. If you're using serverless functions or stateless backends, the state may not be preserved between requests. Check that your state storage (session, database, or cache) is working correctly.
Cookie issues in iframe - if your tool launches in an iframe, Safari and some other browsers block third-party cookies by default. Your OIDC flow may rely on a cookie to preserve state, which Safari drops. If launches work in Chrome but fail in Safari, this is your problem. The fix is to use platform storage via postMessage or redirect to a new tab instead.
Step 3 - Validate the id_token
Once the OIDC flow completes, the LMS sends your tool an id_token containing the LTI launch data. Token validation failures are a common silent failure point.
Check each of these:
- Signature verification - your tool should verify the token signature using the LMS's public keys. If the LMS has rotated its keys recently, your cached keys may be stale. Fetch fresh keys from the LMS's JWKS endpoint.
- Issuer claim - the iss claim in the token must match the issuer you registered for this LMS platform in your tool. Case sensitive.
- Audience claim - the aud claim must contain your tool's client ID.
- Expiry - LTI tokens expire quickly, typically within a few minutes of issuance. If there's a clock skew between your server and the LMS server, tokens may arrive already expired. Check your server's time synchronization.
- Nonce validation - your tool should validate that the nonce in the token matches one it generated. This prevents replay attacks. If your nonce storage is misconfigured, valid launches will be rejected.
Step 4 - Check platform-specific configuration
Each LMS implements LTI slightly differently. If your tool works on one platform but not another, the issue is usually platform-specific configuration.
Canvas - Canvas requires a developer key to be created and enabled before LTI tools work. Check that the developer key is active (not pending). Canvas also has specific requirements around the target_link_uri claim.
Moodle - Moodle's LTI configuration is in the External Tools section under Site Administration. The registration flow differs between Moodle versions. Also check that your tool's domain is not blocked by Moodle's security settings.
Blackboard - Blackboard auto-migrates LTI 1.1 links to 1.3 when you configure a 1.3 tool for the same domain. If you have both 1.1 and 1.3 configured and links are behaving unexpectedly, check whether Blackboard has auto-migrated links you weren't expecting.
Brightspace - Brightspace requires deployment IDs to be configured explicitly. A missing deployment ID in your tool's configuration will cause launch failures even if everything else is correct.
Step 5 - Enable logging and read the errors
If you've checked everything above and still can't find the problem, enable detailed logging on your tool's launch endpoint. Log the full OIDC request, the id_token claims, and any validation errors with their specific failure reason.
Most LTI problems produce a specific error that points directly to the issue - a claim mismatch, an expired token, a missing configuration value. Without logging, you're guessing.
Also check the browser console and network tab when triggering a launch. Some LMS platforms surface error details in the network response that aren't visible in the UI.
FAQ
The launch worked yesterday and broke today. What changed?
Most common causes: LMS updated and changed its JWKS URL or key rotation schedule, your SSL certificate expired, a deployment or configuration change in your tool, or the LMS rotated its signing keys. Start by checking the LMS JWKS URL and your SSL certificate.
We get a blank screen after the OIDC redirect. Where do we look?
This almost always means your tool received the id_token but threw an unhandled error during validation or session setup. Check your server logs for exceptions around token parsing. Also check whether your redirect URI is returning a valid response - a 500 error during the final redirect produces a blank screen.
Launches work for instructors but not students.
Check role-based access controls in your tool. Also check whether your tool expects certain claims that are present for instructors but not students. Some LMS configurations send different claim sets based on role.
The tool launches fine in development but fails in production.
Most likely a URL mismatch - your registered URLs use the development domain and haven't been updated for production. Also check environment-specific configuration like your JWKS URL, client ID, and private key.
Top comments (0)