Troubleshooting Guide

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.

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.

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.

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.

See: PacketTooBigException.

You need to install a valid license key. See Licensing FAQ.

Theme Builder will automatically run in FREE mode on personal, developer or community licensed confluence installs, however you do need to accept the EULA.

You should visit the license details screen and accept the EULA before attempting to use Theme Builder.

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;
}

For more information on the Access Keys feature, see the related blog post.

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.

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

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.

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

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.

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!

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.

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

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.

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.

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.

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;
}

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.

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.

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.

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

Upgrade to Builder 2.0.8 or above to fix this issue.