Skip to main content

Troubleshooting

Solutions for common GitFig issues.

Authentication Issues​

"Authorization pending" won't go away​

  • Complete authorization on GitHub
  • Check correct GitHub account
  • Get a new device code

"Session expired"​

Device codes expire after 15 minutes. Start again.

Wrong account connected​

  1. Sign out from GitFig
  2. Revoke at github.com/settings/applications
  3. Sign in with correct account

Sync Issues​

No variables created​

  • Check JSON has $value fields
  • Verify file mappings configured
  • Check browser console for errors

Variables not updating​

  • Click Pull after changes
  • Check correct branch
  • Verify JSON file changed

"…looks mode-keyed … and was skipped" when pulling​

The file's root keys look like mode names (e.g. light/dark with identical structure inside), but the mapping is set to First mode only. Importing it flat would create broken variables like dark/colors/primary, so GitFig refuses.

  • If the file is mode-keyed: edit the mapping and set Variable Modes to All modes (Variable Modes)
  • If it isn't (two ordinary groups that happen to have identical structure): split those top-level groups into separate files and map each one

New file doesn't appear in the Mapping tree​

Click the refresh icon in the Mapping header. The tree also refreshes on its own after a pull and when new commits land on the branch (checked every 30 seconds).

Push fails​

  • Check write access to repo
  • Branch may be protected
  • Token may have expired

Garbled characters (é, ÃÂ…) in descriptions​

Versions before v1.3.0 could corrupt accented and non-Latin characters when pulling. v1.3.0 fixes the cause; already-corrupted text stays corrupted in Figma. Re-type the affected description (or fix it in the JSON and pull) once, and it will stay clean.

Connection Issues​

"Repository not found"​

  • Use owner/repo format
  • Verify repo access
  • Check spelling

"Branch not found"​

  • Click Refresh for branch list
  • Create branch on GitHub first

CORS Errors​

"Access-Control-Allow-Origin" error​

  • Server may need redeployment
  • Check oauth.gitfig.com is accessible
  • Try again in a few minutes

Performance Issues​

Sync is slow​

  • Large JSON files take longer
  • Many variables = more processing
  • Network affects API calls

Plugin unresponsive​

  • Close and reopen plugin
  • Check Figma memory usage
  • Restart Figma if needed

Understanding Error Messages​

GitFig provides actionable error messages. Here's what common messages mean:

Error MessageCauseSolution
"Authentication expired"GitHub token invalidSign out and sign back in
"Permission denied"Insufficient repo accessCheck repo permissions, try signing out/in
"Rate limit reached"Too many GitHub API callsWait a few minutes, then retry
"Network error"Connection issueCheck internet, try again
"Repository not found"Repo doesn't exist or no accessVerify repo name and permissions
"Branch already exists"Duplicate branch nameChoose a different branch name
"Invalid JSON"Syntax error in token fileCheck file for JSON syntax errors
"No file mappings"Missing configurationGo to Settings to map JSON files

Still Having Issues?​

If your issue isn't covered above:

  1. Check the browser console (Figma DevTools) for error messages
  2. Note the exact steps to reproduce the issue
  3. Ask in the GitFig Community Q&A
  4. Or report a bug in Bug Reports

The community is the fastest way to get help and connect with other GitFig users.