Skip to main content
This page covers the errors and unexpected behaviors reported most often. Each section describes the symptom, explains the most likely cause, and walks you through the fix. If the issue you’re seeing isn’t listed here, use the in-app support button to contact the team.
If Rationale can’t import your Figma file, work through the following checks:
1

Confirm Figma is connected

Go to Settings → Connections and check that the Figma connector shows a connected status (a green dot next to the name). If it doesn’t, click the connector and select Add connector to authorize your Figma account.
2

Check the URL format

Rationale accepts Figma file and design URLs in the format figma.com/file/… or figma.com/design/…. Prototype links (figma.com/proto/…) and embed URLs are not supported. Copy the URL directly from the browser address bar while viewing the file in Figma.
3

Verify file access

Make sure the Figma file is accessible with the account you used to connect Figma in Rationale. If the file is in a team or organization workspace, confirm that your account has at least viewer access to it.
If the Notion page picker shows no pages or is missing pages you expect:
1

Check the Notion connection

Go to Settings → Connections and confirm the Notion connector is connected. If it isn’t, click it and select Add connector to reauthorize.
2

Check which pages were shared during authorization

Rationale can only access the Notion pages that were explicitly shared with the integration at the time you authorized it. If a page is missing, open Notion, navigate to that page, click Share, and grant access to the Rationale integration. Then retry the page picker in Rationale.
Rationale cannot access pages in private sections of your Notion workspace that were not shared during the OAuth flow. You’ll need to share individual pages or databases with the integration.
A gap-free audit result doesn’t necessarily mean something went wrong. Consider the following:
  • Check the Summary tab — the health score shows how closely the design and spec are aligned. A high score means Rationale found the two to be well-matched.
  • Review the Requirements tab — confirm that all requirements from your PRD were detected and mapped. If key requirements are missing, the PRD may not have been parsed fully; try re-importing it.
  • Check PRD coverage — if the PRD is short or written at a high level, there may not be enough detail for Rationale to find contradictions against the designs.
For richer audit results, make sure your PRD includes edge cases, error states, and empty states explicitly — the more specific the spec, the more Rationale has to audit against.
The Dev Handoff tab is intentionally locked until you formally approve the audit. This prevents incomplete or unreviewed audits from being handed off to engineering.To unlock it:
1

Open the Summary or Gaps tab

Navigate to either the Summary tab or the Gaps tab in your project.
2

Approve the audit

Click Approve to mark the audit as reviewed. Once approved, the Dev Handoff tab becomes active.
Approving the audit signals to your team that the design has been reviewed and is ready for engineering. Make sure you’ve addressed or consciously dismissed all gaps before approving.
If you pushed an audit to Linear but no issues appeared:
1

Verify the Linear connection

Go to Settings → Connections and confirm Linear is connected. If it isn’t, reconnect it and try the push again.
2

Check the team selection

In the Linear push dialog, make sure you selected the correct Linear team. Issues are created in the team you select, so if you chose the wrong one they may have been created in a team you don’t normally check.
3

Check Linear for the parent issue

Rationale creates a parent issue for the audit and a sub-issue for each gap. Search Linear for the audit name to find the parent issue — sub-issues are nested under it and may not appear in your default view.
If the PRD panel in your project appears empty or shows an error:
  • If you used a link — Rationale may not have been able to fetch the page. Some links (especially behind sign-in walls or on Confluence Cloud with SSO) can’t be fetched remotely. Try downloading the document and uploading it directly as a .pdf, .doc, .docx, .md, or .txt file.
  • If you used Notion — make sure you selected the correct page in the Notion page picker. If you selected a database or a page you don’t have access to, the content won’t load. Reconnect Notion and try picking the page again.
  • If you uploaded a file — confirm the file format is supported (.pdf, .doc, .docx, .md, .txt) and that the file isn’t corrupted or password-protected.
If a project you created doesn’t appear in your projects list:
  • Use the search bar — the projects view has a search bar at the top. Type part of the project name to filter results.
  • Check your account — confirm you’re logged in with the correct account. If you have multiple accounts (for example, a personal and a work account), the project may be in the other workspace. Log out and sign in with the other account to check.
Projects are tied to your individual workspace and are not shared across accounts unless you’ve invited collaborators.
If your issue isn’t listed here, use the in-app support button (the help icon in the bottom-left corner of the app) to contact the Rationale team. Include a description of the issue, the steps you took, and any error messages you saw so the team can help you faster.