Troubleshooting
Common issues and fixes.
Forgot password or can't sign in
On the login page, use Forgot password? to request a reset link by email. Check spam if you don't see it. Use the same email you signed up with. If you signed up via Figma or GitHub OAuth, sign in with that provider instead of email/password.
Analysis uses demo flow
If you see a yellow banner saying "Demo flow used", Figma could not be loaded. Connect Figma in Settings (OAuth), add a valid Figma file URL to your project, and run analysis again. Ensure your Figma file is shared with the app or is in a team you have access to.
Analysis failed
Check your Figma file URL format (e.g. https://www.figma.com/file/... or https://www.figma.com/design/...). Verify Figma is connected in Settings. If the issue persists, try creating a new project and running analysis with a minimal config.
Figma or GitHub connection fails
If OAuth fails or shows an error: ensure you're not blocking pop-ups or third-party cookies. Try an incognito window or different browser. For Figma, your account must have access to the file you want to analyze. For GitHub, ensure you authorize the requested scopes (repo, etc.). Revoke and reconnect in Settings if the token may be stale.
Export to GitHub not working
Connect GitHub in Settings first and grant repo scope. When exporting from the report, pick a repository you have write access to (the list comes from your GitHub account). Export creates issues on the repo's default branch. If the list is empty, re-authorize GitHub with "repo" scope. See Export & sharing for details.
Analysis stuck or pending
Analysis runs asynchronously. If it stays pending, refresh the page—the report updates when complete. For large Figma files, analysis can take 1–2 minutes. Check that your Figma file URL is valid and the file is accessible.
Analytics overlay shows no data (Spec 6.3)
Connect your analytics provider (PostHog, Amplitude, Mixpanel) in the project Config & analytics tab and save a valid API key. The overlay needs event data that maps to your flow nodes (screen names or step identifiers). If you use custom event names, ensure they match what Blue Painter expects or configure the mapping in Config. See Analytics overlay for setup.
Figma comments missing frame links
Frame links (Figma URLs) appear in comments when your project has a Figma file connected and flow nodes are mapped. Ensure the project's Figma file ID is set and that issue screen names match flow node labels. Without a match, comments still work but omit the direct Figma link.
Analyses limit reached
The free tier allows 3 analyses per month. Your dashboard shows analyses used vs limit. Community support is available for free users. Upgrade to Pro or Team for unlimited analyses and email/priority support.
CI/CD: PR comment not posting (Spec 6.7)
Ensure GitHub is connected in Settings and your workflow uses the correct secrets (FIGMA_FILE_ID, FIGMA_ACCESS_TOKEN). The sample workflow runs when PRs touch figma-export/**—adjust paths to match your design-asset folder or remove the filter to run on every PR. Check the Actions tab in your repo for workflow run logs.
Rules or presets not applying
Analysis rules in Settings apply to new analyses. Project-level overrides (on Config & analytics) take precedence. Vertical preset (e.g. SaaS, Enterprise) is chosen when creating a project or running analysis—ensure you select it in the New analysis wizard. Existing analyses keep their original rules.
Shared report link not accessible
Report links are viewable by recipients who are logged in and have access to the project. Recipients must sign in to Blue Painter. Project access is per-user; team projects share access with team members. If a recipient sees an error, ensure they are signed in and that the project is shared with them.
Markdown vs PDF export
Markdown includes all sections, scores, and issues—ideal for Notion, Confluence, or GitHub Wiki. Print/PDF includes flow diagrams and scores—use it when you need visual reports for stakeholder presentations. For both, use your browser's Print or Save as PDF.