applyToken broken in 2.15 : anyone got it working?

Ismail_Hamila · April 30, 2026, 6:09pm

Hi all,

Building a multi-tenant design system tooling on top of Penpot’s plugin SDK
(via the MCP server, used by an LLM agent to author DS docs/components),
and I’m hitting a hard wall on shape.applyToken().

Context. Working on an open-source firmware project
(openTRNTBL, a Sonos-streaming turntable), the design system is built around Tokens
Studio with 11 sets / 13 themes (light/dark/HC/4 vision modes/density),
imported via drag-drop UI. Now trying to programmatically generate the
token visual documentation directly in Penpot using the plugin API.

Bug. shape.applyToken(tok, ['fill']) consistently throws a generic
error on every token type tested (color, dimension, opacity), regardless
of the signature variation:

Call	Result
`applyToken(tok, ['fill'])`	`Field message is invalid`
`applyToken(tok)` (default property)	`Field message is invalid`
`applyToken(tok, 'fill')`	`Field message is invalid: . Field message is invalid: .`
`tok.applyToShapes([r], ['fill'])`	`Doesn't support name: 0`

Detailed reproduction steps + analysis in the GitHub issue I just opened:

github.com/penpot/penpot

Plugin API: applyToken fails with "Field message is invalid" on color/dimension/opacity tokens (SDK 2.15)

opened 05:34PM - 30 Apr 26 UTC

hamilaism

## Setup | | | |---|---| | Penpot version | 2.15.0 (production, design.penpot.a…pp) | | MCP server | `@penpot/mcp@2.15.0-rc.2` (tagged `latest` + `stable` on npm) | | MCP mode | Remote (`design.penpot.app/mcp/stream?userToken=…`) | | Client | LLM with tool-use via `mcp__penpot__execute_code` | ## Bug — `applyToken` rejects all token types with generic error ```javascript const tokens = penpot.library.local.tokens; const core = tokens.sets.find(s => s.name === 'core'); const colorTok = core.tokens.find(t => t.name === 'palette.gold.50'); // colorTok = { id, name: 'palette.gold.50', type: 'color', value: '#563f00', description } const r = penpot.createRectangle(); r.x = 100; r.y = 100; r.resize(80, 80); r.applyToken(colorTok, ['fill']); // throws: [PENPOT PLUGIN] Value not valid: Field message is invalid: . Code: :error ``` **Tested signatures, all fail with the same generic error** (or a similar one for `applyToShapes`): | Signature | Result | |---|---| | `r.applyToken(tok, ['fill'])` | `Field message is invalid` | | `r.applyToken(tok)` (default property) | `Field message is invalid` | | `r.applyToken(tok, 'fill')` (string instead of array) | `Field message is invalid: . Field message is invalid: .` | | `tok.applyToShapes([r], ['fill'])` | `Doesn't support name: 0` | **Not specific to color tokens** — same error on `dimension` token (`applyToken(dimTok, ['width'])`) and `opacity` token (`applyToken(opTok, ['opacity'])`). Bug appears to affect the entire `applyToken` API. The token referenced is validly resolved: - has an `id` and `type: 'color' | 'dimension' | 'opacity'` - the parent set is `active === true` (verified after activating the corresponding theme) - the rectangle is validly created (appears on canvas with default fill) Tested on a file with 11 sets / 13 themes / 478 tokens imported via drag-drop UI (the SDK bulk import path has its own bugs which I worked around by using the drag-drop path). ## Expected vs Observed | | | |---|---| | Expected | shape.fills bound to the token, `shape.tokens.fill === 'palette.gold.50'`, `getStyle` reflects the resolved value | | Observed | Generic error message with no actionable detail; shape stays unmodified | ## Why blocking `applyToken` is the only documented mechanism to programmatically bind a shape to a design token via the plugin SDK. Without it: - Cannot generate visual documentation of design tokens (swatches, samples) that stays linked to the token's source value - Cannot author/modify component instances tied to tokens via plugin - Cannot integrate token systems with external automation (Style Dictionary sync, MCP-driven design system tooling, etc.) ## Workaround used For color documentation we fell back to `Library.createColor()` + `LibraryColor.asFill()`, which works correctly. Trade-off: duplication between Library Colors and Tokens Studio tokens, both must be kept in sync via external script. For non-color tokens (dimension, opacity, etc.) no equivalent workaround — values inlined as plain strings, breaking the lineage to source. ## Suggestions 1. **Improve error messages** — `Value not valid: Field message is invalid: . Code: :error` provides no diagnostic signal. Minimum: include the field name, received value, expected schema. 2. **Document the matrix of supported `(token type × shape type × property)` combinations** in the plugin API docs. 3. **Possibly the same async state race as #8698** — the token has a valid `id` and the active set is `active === true`, but `applyToken` may still fail because the internal state map hasn't propagated yet. Worth checking if the same fix that addressed `theme.addSet()` async race applies here. ## Related - #8698 (`theme.addSet` async state race — closed, fixed) - #7916 (Plugin API for tokens — initial feature) - Forum thread ["API and MCP issues"](https://community.penpot.app/t/api-and-mcp-issues/9962) — similar `200 OK` / persistence-fails class of bugs Happy to file separate issues for related bugs encountered while investigating this one (`set.remove()` followed by `addSet({same name})` rejects for collision; `theme.activeSets` ghost entries with `id: ""` after drag-drop import) if useful.

Workaround currently used. Fall back to Library.createColor() +
LibraryColor.asFill() for colors — works fine, but breaks the
token->shape lineage and forces a duplicated layer (Library Colors must
stay in sync with Tokens Studio tokens via external script). For
non-color tokens (dimension, opacity, font-size…), no clean equivalent.

Asking the community:

Anyone using applyToken successfully on the latest 2.15 SDK? If yes,
what’s the magic signature?
Has the Penpot team mentioned this bug or its fix on the roadmap?
Anyone using a different mirror approach (Library + script sync) at
scale and has feedback on the trade-offs?

The bug feels related to the async state race that was fixed in #8698
(theme.addSet) — same generic “Field message is invalid” error pattern.
Curious if anyone else has investigated.

Thanks!

Topic		Replies	Views
Tokens - Initial Impressions Help us improve Penpot community	24	717	March 9, 2026
Expose Tokens to pluggins Feature requests	3	63	April 24, 2026
Token API works well! Plugins design-tokens	1	23	April 24, 2026
How to apply typography tokens in the editor? Ask the community tokens , design-tokens	8	175	January 15, 2026
Is applying design tokens experience going to be fixed? Help us improve Penpot design	8	307	March 13, 2026

applyToken broken in 2.15 : anyone got it working?

Related topics

Design as Code