From Jira 12.0, Confluence 11.0, Bitbucket 11.0, Bamboo 13.0, and Crowd 8.0, some characters are no longer allowed in a web-resource <context> name. A plugin that declares one fails to install, with an error naming the context and the character.

Earlier versions accepted these names, but would silently fail to serve the expected bundle.

This affects plugins that declare a <context>, or generate one from a webpack entry point or chunk name with URL unsafe characters. If it doesn't, there's no action required.

Illegal characters

/ ? + , # % &, whitespace, and anything outside visible ASCII. A context name must not be empty, and must not start with -.

Everything else still works, including :, ., and - anywhere but the first position. The recommended com.acme.plugin.fancy-context style is unaffected.

Relevant errors

At plugin install or startup:

1
2
3
4
The web-resource context 'widget/theme-switcher/entry' contains characters that cannot be represented in a batch URL: '/'.
The web-resource context '-legacy' must not start with '-', which marks a context as excluded in a batch URL.
A web-resource context must not be empty.

What to do

1. Check the declared web-resource contexts

Search the atlassian-plugin.xml and any other file with web-resource descriptors for <context> elements.

If @atlassian/webresource-webpack-plugin is used, check the generated XML in the plugin build output directory too. Before version 7.2.0, a nested entry point name such as widget/theme-switcher/entry became a context of the same name.

2. Upgrade `@atlassian/webresource-webpack-plugin` to 7.2.0 or later

Contexts taken from entry point and chunk names are renamed to a valid value, e.g. widget/theme-switcher/entry becomes widget-theme-switcher-entry. The build logging shows warnings if the name was altered. Contexts manually defined in contextMap are left unchanged, so an invalid one will fail the build. To choose the name rather than accept the generated one, set it in contextMap.

3. Rename any invalid context

A context name is part of a plugin's public surface, so update every place that names it:

<context> elements in plugin web-resource descriptors
$webResourceManager.requireResourcesForContext("…") in Velocity templates
RequiredResources.requireContext("…") calls in Java
documentation with publicly shared contexts

Reference

Web Resource plugin module — the <context> element and how contexts are batched.