Troubleshooting
Symptoms, causes, fixes.
Applying a token did nothing
The most common report, and usually one of these:
| Cause | Check |
|---|---|
| The target does not exist on that layer type | Corner radius on a line, padding on a frame without auto layout, and font targets on a non-text layer are skipped silently. Pick a target the layer actually has |
| The value is a broken reference | The tile shows a broken-link icon and red text. See references |
| The type cannot be applied at all | duration, cubicBezier, transition, gradient have no Figma equivalent |
| A font weight or family token | See the caveats on font weight and font family. Use a typography token instead |
A “Token applied and reference saved” message means nothing errored — not that every layer visibly changed.
“add a Drop Shadow effect first”
The shadow colour and shadow offset targets modify an existing effect; they do not create one. Add a drop or inner shadow to the layer in Figma, then apply.
To create the shadow from a token instead, use a shadow token, which writes the whole effect.
“Reference cannot be resolved”
The token this one aliases is not visible. In order of likelihood:
- The target set is Disabled under the active theme → set it to Reference or Enabled in the theme dialog
- The target token was deleted → deleting does not rewrite referrers
- The path is wrong → it is the full path, with
/from the set path written as.
A border width in rem is far too thin
Known bug: the border token’s width slot skips the rem → px conversion, so
0.5rem becomes a stroke weight of 0.5. Use px for border widths.
The value I typed was rejected
| Type | Rejects |
|---|---|
| Dimension | Every unit except px and rem — no em, %, vh, pt |
| Color | Colour strings that resolve to a space outside the supported 14 |
| Cubic Bézier | X coordinates outside 0–1 |
| Font weight | Numbers outside 1–1000, and keywords not in the DTCG list |
| Stroke style | The object form — keywords only in the dialog |
Names are rejected for spaces, /, .., or a leading or trailing ..
My tokens disappeared
| Did you… | |
|---|---|
| Save in the JSON editor? | That replaces the whole document with the editor’s contents |
| Pull from a sync provider? | That replaces local tokens with the remote |
| Delete a token set? | That deletes every token in it |
There is no undo. Restore from an export.
If the panel is empty on open with no action from you, the stored data may have failed to parse — the console shows “Failed to parse chunked data”.
Sync will not connect
| Provider | |
|---|---|
| GitLab or HTTP endpoint | These cannot work today — their domains are not in the plugin’s network allowlist. Use GitHub |
| GitHub | Check the token has read and write access to that repository, the branch exists, and owner/name is exact |
Remember the path rule: ending in .json means single-file mode, anything else
means directory mode.
A pull overwrote my local work
Pull replaces, it does not merge. Recover from a JSON export if you have one; otherwise the local state is gone.
Going forward: export before pulling, and let one person own pushes per document.
A font will not load
“Failed to load font …” means Figma does not have that family, or not in the resolved style.
- Check the family name matches Figma exactly, including spacing
- For a typography token, the weight snaps to the nearest Figma style — a family without a Semi Bold falls back to the nearest one it has
- A fallback stack works in a typography token, but not in a standalone font family token
The plugin window is the wrong size
Drag the handle at the bottom-right. The size is remembered per document, within 400×300 to 1200×900.
Colours look different on canvas than in the token
Expected for wide-gamut values. Figma’s canvas is sRGB, so a P3, Rec2020, or out-of-sRGB OKLCH colour is gamut-mapped for display. The stored and exported token keeps the original value.
Still stuck
Collect: the token type, its exact $value from the JSON editor, the layer type,
the apply target, and the exact message. That is usually enough to identify the
cause without a file.