Skip to end of metadata
Go to start of metadata

Common issues and how to fix them.You can also review our Release Notes to find out about other bugs or features in various versions of Theme Builder.

By far the most common issues (all covered by our installation guide):

  • Make sure you've disabled the "Compatibility Macros" plugin - this is the No. 1 cause of support requests!
  • Make sure you've installed the correct version of "Page Information Tools" plugin
  • Make sure you've installed the correct version of "Content Formatting Macros" plugin
  • If you've downloaded the plugin for manual installation, check that Internet Explorer has not renamed it to a ".zip" file (if it has - rename back to .jar)

If you're using Theme Builder 3.0 Beta 27 or above, you'll also need to accept the End User License Agreement (EULA) before you can fully use the plugin.

Theme Builder Installation and Upgrade Issues

These issues can occur when first installing or upgrading from an earlier version of Theme Builder. You may also like to refer to the section on #General Issues.

 I can't install Theme Builder via the Plugin Repository

This issue only affects Builder 1.x and 2.x.

The plugin repository was modified so that it keeps a count of the number of times a plugin is installed - this modification broke the ability for the repository to install password protected plugins.

You'll need to manually download the plugin (URL and login details are in the email you received when you purchased Builder) and install it using either the Plugin Manager or the "Upload" tab in the Plugin Repository.

(warning) If uploading via the plugin manager, remember to uninstall the old version of the plugin first (the Plugin Repository "Upload" tab will do this automatically).

This issue does not affect Builder 3.0 and above.

 I've upgraded to Theme Builder 3.x or above and my 2.x settings have disappeared

You will need to import the 2.x theme settings using the following procedure:

  • Go in to the Confluence "Administration" console
  • Click the "Builder Administration" (or "Theme Administration" depending on the version of Builder) link
  • Use the "Import all layouts" option on the Backup Tab

Once the old theme configurations have been imported (and converted to layouts) you can then apply them to spaces using the Manage Spaces Tab.

 A 'max_allowed_packet' error occurs when installing or upgrading

If you're using MySQL database, you may encounter the following issue:

java.lang.RuntimeException: There was a problem evicting or flushing a PluginData object
at com.atlassian.confluence.plugin.persistence.hibernate.HibernatePluginDataDao.saveOrUpdate(HibernatePluginDataDao.java:65)
caused by: net.sf.hibernate.exception.GenericJDBCException: could not insert: com.atlassian.confluence.plugin.persistence.PluginData#3375106
at net.sf.hibernate.exception.ErrorCodeConverter.handledNonSpecificException(ErrorCodeConverter.java:90)
caused by: com.mysql.jdbc.PacketTooBigException: Packet for query is too large (3063507 > 1048576). You can change this value on the server by setting the max_allowed_packet' variable.
at com.mysql.jdbc.MysqlIO.send(MysqlIO.java:2691)

To resolve this issue, simply increase the max_allowed_packet setting in your MySQL config to 4M using the command line shell as follows:

shell> mysql --max_allowed_packet=4M

See Also: PacketTooBigException.

 TypeError: exception is undefined (MySQL specific)

Theme Customisation Issues

The following issues are related to various theme settings.

 Skip navigation link not hidden in Builder 3.x and above

In Theme Builder 3.0 and above, a new feature adds pop-up access key hints at the top of the page. In normal use, these hints will not been seen however there are a couple of things that cause them to be displayed...

If you have disabled CSS or are using a browser which does not support CSS, the links will always be shown - this is expected behaviour and is required for compliance with accessibility laws throughout Europe and other parts of the world.

If you have disabled the "Builder Default CSS" option in the CSS Tab, you will need to add some "Custom CSS" to make the hints work properly as follows:

#accessKeys {
 margin: 0; padding: 0;
}
#accessKeys dt {
 margin: 0;
 padding: 0;
 position: absolute;
 top: -9999px;
 left: 0;
}
#accessKeys dd {
 margin: 0;
 padding: 0;
}
#accessKeys dd a {
 position: absolute;
 top: -9999px;
 left: 0;
}
#accessKeys dd a:focus, #accessKeys dd a:active {
 background-color: #3556a2;
 color: #fff;
 top: 0;
 font-size: 1.2em;
 padding: .5em;
}
 When I click Upload Settings (Builder 2.x) nothing happens

It's a known bug in Theme Builder 2.x - choose the option twice and the upload panel will appear.

This bug does not affect Builder 3.0 or above.

General Issues

These issues are not directly related to the Theme Builder plugin, but are often associated with it.

 Macro not found: tr

Install the "Content Formatting Macros" plugin which contains macros required for the layout of the title panel.

 The title panel looks messy

It's likely that the "table" macro within Atlassian's "Compatibility Macros" plugin is enabled.

Disable the "table" macro in the "Compatibility Macros" plugin (or the entire plugin) using the Plugin Manager (or plugin repository).

Note: We plan to add a table2 alias to our table macro in the Content Formatting Macros plugin at a later date - this would allow you to run both plugins alongside each other.

 Macro not found: page-info

Install the the "Page Information Tools" plugin version that's applicable to your version of Confluence.

 Macros used in panels are showing errors in Space Admin screens

Many Confluence macros are developed for use only on wiki pages and blog posts. However, Theme Builder allows you to use macros within the theme layout in which case they get rendered throughout the entire space causing errors to appear when those macros find themselves in unexpected places.

To solve this issue, use the builder-show macro, for example:

{builder-show:context=page,blogpost}
... your macros here ...
{builder-show}

That will only show the macros when you are viewing a wiki page or blog post, and hide them everywhere else preventing the errors from appearing.

 Edit labels is always shown and clicking the edit link doesn't do anything

This is caused by the table macro in the "Compatibility Macros" plugin (or "incompatibility macros" as we fondly refer to it here at Adaptavist!). Disable the table macro in that plugin (using plugin manager or plugin repository client) or preferably the entire macro!

 I'm using Confluence in clustered mode and theme settings don't appear on all nodes

This issue only applies to Theme Builder 1.x and 2.x. You will need to upgrade to Theme Builder 3.0 or above for compatibility with clustered environments.

Note: You will also need the correct form of Theme Builder license, i.e. one license per node.

 I'm using external user authentication and some admin links are not appearing in the menus

Please upgrade to Confluence 2.5.x or above and Builder 2.0.9 or above to resolve this issue.

 My Dashboard is in one long column

This issue affects Theme Builder 3.0 and above which uses the "table" macro from the "Content Formatting" plugin to structure the dashboard.

The problem is caused by a conflicting "table" macro in one of the bundled plugins, "Compatibility Macros".

Disable the "Compatibility Macros" plugin using Plugin Manager.

 Versioned attachments not collapsing

This issue affects Confluence 2.7.1 and above. To solve, add the following to the custom CSS for your layout

.hidden {
  display: none;
}

Reason:
Confluence 2.7.1 and onwards uses an external attachments.js rather than inline javascript, the older inline code modified the display property of the <TR>'s class directly. The new code in the external file adds another class, "hidden", to the <TR>. This class is not defined by confluence inline or in any CSS files, this issue also affects the default confluence theme, and is not caused by Theme Builder.

Confluence Upgrade Issues

The following issues have been reported when upgrading Confluence.

 Confluence 2.7 - Theme Builder not working

Atlassian changed the way the site administration privileges work in Confluence 2.7 - if you're using an earlier version of Theme Builder, you'll need to upgrade to Theme Builder 3.0 Beta 23 or later for compatibility with Confluence 2.7.

 Confluence 2.6.x (or later) tabs or link properties distorted in Builder 2.x

Atlassian changed the structure of tabs in Confluence 2.6.0 and above - if you're still using Builder 2.x then there are two options to solve this:

The easiest option is to upgrade to Builder 3.0 or above which has more dynamic support for changes to Confluence and it's style sheets.

Note: If your link properties window is distorted, you should first upgrade to Confluence 2.6.2 which fixes several bugs found in Confluence 2.6.0 and 2.6.1.

If you want to continue using Builder 2.0.x, you can add the following CSS to the bottom of the "Custom CSS" setting in Theme Configuration:

/**** 2.6 tabs ****/
.tabnav, .comment .tabnav {
border-bottom:1px solid #3C78B5;
display:inline;
float:left;
font-size:10pt;
font-weight:bold;
list-style-position:outside;
margin:0pt;
padding:0pt;
width:100%;
}
.after-tabnav {
clear:both;
}
.tabnav li.tabs {
display:block;
float:left;
list-style-image:none;
list-style-position:outside;
list-style-type:none;
margin:0pt 0pt -1px 10px;
}
.tabnav .tabs a {
background:#3C78B5 none repeat scroll 0%;
border-color:#3C78B5 rgb(60, 120, 181) -moz-use-text-color;
border-style:solid solid none;
border-width:1px 1px medium;
display:block;
float:left;
margin:5px 0pt 0pt 3px;
padding:5px 5px 4px;
text-decoration:none;
}
.tabnav .tabs a:link, .tabnav .tabs a:visited {
color:#FFFFFF;
}
.tabnav .tabs a:hover {
background:#003366 none repeat scroll 0%;
border-color:#003366;
color:#FFFFFF;
}
.tabnav .tabs a.current {
background:white none repeat scroll 0%;
border-bottom:1px solid white;
color:black;
}
.tabnav .tabs a.current:link, .tabnav .tabs a.current:visited {
color:black;
}
.tabnav .tabs a.current:hover {
background:white none repeat scroll 0%;
border-bottom:1px solid white;
color:black;
}
.tabnav .spaceActionLinks {
display:block;
float:right;
margin:0pt;
}
.tabnav .spaceActionLinks a {
border:0pt none;
display:inline;
float:left;
font-weight:normal;
margin:1px 3px;
padding:8px 5px 3px;
text-decoration:none;
white-space:nowrap;
}
.tabnav .spaceActionLinks a span {
text-decoration:underline;
}
.tabnav .spaceActionLinks a:link {
color:#003366;
}
.tabnav .spaceActionLinks a:visited {
color:#003366;
}
.tabnav .spaceActionLinks a.current {
color:black;
}
.tabnav .spaceActionLinks a.current span {
text-decoration:none;
}
.tabnav .spaceActionLinks a.current:link {
color:black;
}
.tabnav .spaceActionLinks a.current:visited {
color:black;
}
.tabnav .nontabs {
display:block;
float:left;
margin:5px 0pt 0pt 3px;
padding:0pt;
}
.tabnav #markupTab, .tabnav #wysiwygTab, .tabnav .tabs #previewTab {
font-size:9pt;
font-weight:normal;
margin:8px 0pt 0pt 3px;
padding:3px 5px 2px;
}
.tabnav #spacesLabel {
float:left;
margin-top:5px;
padding:4px 6px;
}
.tabnav-box {
border-bottom:1px solid #3C78B5;
border-left:1px solid #3C78B5;
border-right:1px solid #3C78B5;
padding:8px;
}
 I've upgraded Confluence and all the Builder 2.x theme settings have disappeared

This issue only applies to Theme Builder 2.x and earlier.

If you've upgraded from Confluence 2.2.x (or earlier) to 2.3.x (or later) it's likely that the /config folder wasn't copied over in the upgrade process. Simply copy the /config folder from the old install to the new install and all the theme settings should come back.

Note: We have also had reports of this issue when upgrading from Confluence 2.3.x (or above) to a later version. Please check that the /config folder has been copied across during the upgrade - if not, manually copy it to the new Confluence install.

This issue will not affect Builder version 3 or above because settings are be stored in the database rather than XML files in the /config folder.

 Error formatting macro: page-info: java.lang.IncompatibleClassChangeError: org.joda.time.format.DateTimeFormat

If you've just upgraded to Confluence 2.6 or above you'll need to upgrade the "Page Information Tools" plugin to version 1.2.6 or above.

 I've upgraded Confluence and the search box now appears in a different position

Disable the "table" macro in Atlassian's "Compatibility Macros" (or the whole plugin if you don't need it.

See "The title panel looks messy" topic at the top of this page for more information and additional issues that may cause this effect.

 I've upgraded to Confluence 2.5.x or later and page permissions aren't working

Upgrade to Theme Builder 2.0.8 or later to fix this issue.

 I've upgraded to Confluence 2.5.x or later and labels aren't working properly

Upgrade to Builder 2.0.8 or above to fix this issue.