Troubleshooting

Troubleshooting

Common Errors

"Invalid token"

Causes:

• Token was copied incorrectly (should start with figd_)
• Token has expired (Figma PATs expire after 90 days)
• Token was revoked

Solutions:

1. Generate a new PAT at Figma Settings
2. Copy the entire token (including the figd_ prefix)
3. Paste it in Figma Sync → Settings
4. Click Save Settings

"Rate limit exceeded" (429)

Causes:

• Too many rapid requests to Figma API
• The plugin has built-in rate limiting (0.5s delay), but Figma may still return 429 on burst

Solutions:

• Wait ~60 seconds and try again
• Reduce usage frequency
• The plugin will auto-retry up to 3 times on 429

"File not found"

Causes:

• File key is incorrect
• Your token doesn't have access to the file
• The file was deleted or moved

Solutions:

• Verify the file key from the URL (figma.com/file/KEY/...)
• Check that your token has "Read" access to the file
• Make sure the file still exists in your Figma account

Import hangs or times out

Causes:

• Large files with many nodes take longer to process
• Slow internet connection
• Figma API rate limiting

Solutions:

• Increase API timeout: Add this filter to your theme's functions.php:

  add_filter('hello_figma_api_timeout', function() { return 300; });

• Import individual frames instead of the whole file
• Check your internet connection speed
• Try again after a few minutes

"Failed to convert Figma file"

Causes:

• The API response was empty or malformed
• Rate limiting (429 response)
• Network error

Solutions:

• Check the WordPress debug log for details
• Enable WordPress debugging in wp-config.php:

  define('WP_DEBUG', true);
  define('WP_DEBUG_LOG', true);

• Check /wp-content/debug.log for Figma API error details

Layout Issues

Elements are not in the right position

Possible causes:

• Rotated elements (rotation > 0.01°) skip absolute positioning in v1
• The parent frame uses auto-layout but some children have layoutPositioning: 'ABSOLUTE'
• The bounding box calculation may differ between Figma and Elementor

Solutions:

• Check if the element has rotation in Figma (rotate = 0° for best results)
• Ensure your parent frame has the correct layout settings
• Use Elementor's position controls to manually adjust

Styles look different in Elementor

Possible causes:

• Figma uses its own rendering engine (not CSS)
• Anti-aliasing and sub-pixel rendering differ
• Some gradient types or complex shadows may not have direct Elementor equivalents

Solutions:

• Accept minor visual differences (normal between design tools and browsers)
• Manually adjust complex gradients in Elementor
• Report specific mismatches as GitHub issues

Images not showing

Possible causes:

• Image download failed
• Figma fill type is not supported (e.g., GIF, SVG fill)
• The image URL expired

Solutions:

• Re-import the frame
• Make sure the image fill type is supported (PNG, JPG)
• Check that your Figma token has access to download images

WordPress Issues

"Headers already sent" error

Cause: PHP whitespace or output before plugin header.

Solution: Check that no files have extra whitespace after ?> or before <?php. The plugin files use strict typing and no closing ?> tag.

"Class not found" error

Cause: Autoloader could not find a class file.

Solution:

• Verify the file exists at the expected path
• Check the namespace matches the file naming convention:
  • HelloFigma\Some_Class → includes/class-some-class.php
  • HelloFigma\Widgets\Some_Widget → widgets/class-some-widget.php

Plugin conflicts

The plugin registers custom Elementor widgets. If another plugin registers widgets with the same names, there may be conflicts. The widget names are prefixed with Figma_ to minimize this risk.

Debug Mode

To enable debug logging:

1. Add to wp-config.php:

   define('WP_DEBUG', true);
   define('WP_DEBUG_LOG', true);
   define('WP_DEBUG_DISPLAY', false);

2. Check /wp-content/debug.log for plugin logs
3. Plugin logs are prefixed with [HelloFigma] in the log entries

Getting Help

If you can't resolve your issue:

1. Search existing issues — GitHub Issues
2. Open a new issue — include:
   • WordPress version
   • Elementor version
   • PHP version
   • Plugin version
   • Steps to reproduce
   • Relevant error logs
3. Start a Discussion — GitHub Discussions