Troubleshooting

Troubleshooting Figma integration issues

Troubleshooting Figma integration issues

Overview

This guide covers common issues users encounter when using the Figma integration in Workflow, including authorization problems, comment syncing failures, and plugin errors. For general setup instructions, see How to use the Figma integration in Workflow.

Quick fixes by symptom

Authorization and connection issues

Issue: Figma option is missing from Settings

What's happening: You don't see a Figma option in your Settings menu under the USER section.

Likely cause: The Figma integration feature flag is not enabled for your account or workspace.

How to fix it:

  1. Refresh the Workflow page and check Settings again.

  2. If it's still missing, your account may not have access to this feature yet.

  3. Contact support and provide your account email. Our team can verify whether the feature flag is active for your workspace.

Issue: "Figma API connection failed" message

What's happening: You clicked "Connect to Figma" but received an error message instead of a success confirmation.

Likely cause: The OAuth authorization didn't complete. This can happen due to browser settings, network issues, or if you didn't authorize the connection in Figma.

How to fix it:

  1. Ensure your browser allows popups and redirects from Figma (check popup blockers and ad blockers).

  2. Make sure you're logged into your Figma account before clicking "Connect to Figma."

  3. Refresh the Workflow page and try connecting again.

  4. Clear your browser cache and try a different browser if the issue persists.

  5. If you see a Figma authorization dialog, click "Authorize" to grant permissions.

  6. If the error continues, contact support with a screenshot of the error message.

OAuth timeout: Figma OAuth authorization must be completed within 3 minutes. If you don't finish the process in time, the connection will expire and you'll need to start over.

Comment syncing issues

Issue: Comments are not syncing to Figma

What's happening: You left a comment on a Figma design or prototype in Workflow, but it didn't appear in Figma.

Likely causes:

  • Figma integration is not authorized in your Workflow account

  • You're commenting on a Figma prototype link (not a design uploaded via the plugin)

  • The Figma file is still processing and not ready for comments yet

  • Your Figma OAuth token has expired

How to fix it:

  1. Go to Settings › Figma and verify that your Figma account is connected (you should see "Figma API connection added" or a status showing you're authorized).

  2. Check whether you're commenting on a Figma design (uploaded via plugin) or a Figma prototype (added via link). Comment syncing only works for designs uploaded via the plugin.

  3. For prototype links, you must open the prototype in Figma directly to leave comments. This is a limitation of the current integration.

  4. If the design is newly uploaded, wait a minute for Workflow to finish processing it before leaving comments.

  5. If your Figma authorization was from over a year ago, your OAuth token may have expired. Try disconnecting and reconnecting your Figma account in Settings.

  6. If comments still aren't syncing after these steps, contact support with the Figma file name, when the design was uploaded, and the time you left the comment.

Issue: Comments appear in Workflow but not in Figma

What's happening: Your comment shows up in Workflow, but when you check the Figma file, the comment isn't there.

Likely causes:

  • The sync is still in progress (can take 10-30 seconds)

  • You don't have the correct permissions on the Figma file

  • The Figma file was deleted or the design was moved to a different team

How to fix it:

  1. Wait 30 seconds and refresh your Figma file to see if the comment appears.

  2. In Figma, verify you have edit access to the file. Comments can only sync to files you can edit.

  3. Check that the Figma file still exists and the design hasn't been moved or deleted.

  4. If the design was uploaded long ago, verify it's still accessible in your Figma workspace.

  5. Try leaving another comment to test if syncing works now.

Plugin and upload issues

Issue: Cannot find the Workflow Figma plugin

What's happening: You clicked "Get Figma plugin" but can't locate the plugin in the Figma Community, or the link doesn't work.

Likely cause: The plugin link may not be loading, or you're on a different Figma instance (e.g., Figma Dev, different region).

How to fix it:

  1. Visit the Figma Community directly: figma.com/community

  2. Search for "Workflow" in the plugins section.

  3. Look for the plugin with the description "Send designs to Workflow for feedback" or similar.

  4. Alternatively, use the direct link: figma.com/community/plugin/1194400816695978796/workflow

  5. Click Install and confirm you want to add it to your Figma account.

  6. If the direct link doesn't work, ensure your Figma account has internet access and is on the latest version.

Issue: Design is not uploading from the plugin

What's happening: You opened the Workflow plugin in Figma, selected your document, clicked Run, but nothing happened or you got an error.

Likely causes:

  • The Figma file is very large and taking longer to process

  • You don't have edit access to the Figma file

  • Your internet connection is unstable

  • The Workflow plugin is out of date or cached

How to fix it:

  1. Verify you own or have edit access to the Figma file you're trying to upload.

  2. Check that you're selecting the correct Workflow workspace and document in the plugin.

  3. Click Run and wait 10-15 seconds. Large files can take longer to upload.

  4. If nothing happens, check your internet connection and try again.

  5. If the plugin seems stuck, reload it by closing and reopening the Figma file.

  6. Close the plugin and reopen Figma to clear any cached data.

  7. Try uploading a smaller Figma file first to test if the plugin is working.

  8. If you still can't upload, contact support with your Figma file name and size.

Issue: Figma file shows as "unprocessed" in Workflow

What's happening: Your Figma design uploaded to Workflow, but it displays as "unprocessed?" and you can't view or comment on it.

Likely cause: Workflow is still processing the uploaded file. This usually resolves itself within 1-2 minutes.

How to fix it:

  1. Wait 1-2 minutes for Workflow to finish processing the file.

  2. Refresh the page to see the latest status.

  3. If it's still showing as unprocessed after 5 minutes, try uploading the design again.

  4. If this persists, contact support with the file name and upload time.

What's happening: You tried to add a Figma prototype link but got an error saying the link is invalid.

Likely cause: The prototype link is not publicly accessible, or it's not shared with the right permissions.

How to fix it:

  1. In Figma, open the prototype file.

  2. Click the Share button and check the sharing settings.

  3. Make sure the link is set to "Anyone with the link can view" (not "private" or "restricted").

  4. Copy the updated link.

  5. Return to Workflow and paste the new link into the Figma prototype field.

  6. Click Add. The prototype should now load.

Pro tip: If you want to keep the prototype private, invite reviewers directly to Workflow using a zero-signup link instead of sharing a public Figma prototype link.

Issue: "Open this prototype in Figma to comment" appears when I try to comment

What's happening: You're trying to leave a comment on a Figma prototype in Workflow, but a dialog appears telling you to open it in Figma instead.

Likely cause: You added the prototype using a link rather than uploading it via the plugin. Prototype links don't support direct commenting in Workflow.

How to fix it:

  1. Click the "Comment in Figma" button to open the prototype in Figma.

  2. Leave your comment directly in the Figma prototype.

  3. Return to Workflow to continue your review.

  4. For full comment syncing support, use the Workflow Figma plugin to upload designs instead of pasting links.

Still need help?

If you've tried these troubleshooting steps and the issue persists, gather the following information before contacting support:

  • Your Figma account email address

  • The exact error message (screenshot if possible)

  • Which version of the Figma plugin you have installed (if applicable)

  • Whether you're trying to upload a design or link a prototype

  • The name of the Figma file or prototype you're having trouble with

  • When the issue started (new upload, or ongoing problem)

  • Steps you've already tried to resolve the issue

Provide this information to our support team, and we'll investigate and get you back on track.

Was this helpful?
Was this helpful?