Detecting unknown attachments in Confluence - How to use ScriptRunner for tidy Confluence pages - Actonic – Unfolding your potential
We have outsourced our Atlassian licensing and services business to the newly founded Seibert Solutions GmbH. Actonic's products will be further developed under the usual name.

Detecting unknown attachments in Confluence – How to use ScriptRunner for tidy Confluence pages


If you've been using Confluence for a while, you've probably encountered the following problem more than once: You go to an important Confluence page that you’ve created some time ago or that a colleague sent you and want to open a significant file stored on the page. However, where you would normally see the file preview, an “Unknown Attachment” icon appears.
Therefore, you cannot open the desired file and work with it.

This problem often causes unnecessary queries or a longer search for the desired file, which can also put your project behind schedule.

In general, it is important to always maintain your Confluence pages and replace these unknown attachments with the correct files. Though, it is especially important when you are about to migrate your Confluence instance, because the resulting confusion often makes it harder to find data again.

Exactly this problem with many "Unknown Attachments" icons occurred with one of our customers. The customer had been using Confluence for 15 years and was about to migrate from server to cloud. That's why he asked our Atlassian Consultant Victoria for help. Victoria immediately knew what to do and helped the customer solve the problem quickly and effectively.

In this article, we will explain why this problem occurs and how you can find all these "Unknown Attachments" on your instance in no time, using our consultant Victoria's method to replace them with the correct file.

“Unknown Attachment” in Confluence – this is why the problem arises

When you place files on a Confluence page, it is not the files themselves that are saved on your Confluence page, but the file path where the file is stored on your server. Confluence generates a file preview that you can click on to go to the file location and open the file.

Now, if the file that was stored on the Confluence page is moved or deleted from the original file path, Confluence will no longer recognize the file on the file path and the “Unknown Attachment” icon will appear.

Thus, Confluence cannot find the file, and you have to search for the changed location first. Often it happens that you need the file urgently when you go to the site, and as a result, you get behind with your work.

In the case of our client, over the 15 years of his Confluence use, many references to files have been lost or moved. This caused him to see many such “Unknown Attachment” icons in Confluence. Since the customer was about to migrate from server to cloud, it was important for him to carefully clean up the Confluence instance before the migration in order to hand it over in a well-maintained manner. This required replacing the icons with the correct files.

You now understand why it is important to prevent this issue and replace the “Unknown Attachments” icon with the actual file path to the file. You will learn how to do this most quickly in the following section.

“Unknown Attachment” in Confluence – how to solve the problem

Attention: The suggested solution has been tested by us so far only on Server and Data Center.

Our consultant Victoria used ScriptRunner to solve the problem. For the following solution, you also need this add-on for your Confluence instance.

You can find ScriptRunner here:

Step 1:

Open the “Confluence Administration” menu, which you can find via the cogwheel at the top right of your Confluence page, and click on “User management”.

Step 2:

In the “SCRIPTRUNNER” pop-up menu that appears, select the “Console” field.

Step 3:

On the Console (see the black area in the screenshot), under Script, paste the code below.

Important: In the ” ” field on line 18, insert the key of your Space. Example: [“DOCS”, “DEV”, “ABC”]

def spaceList = [""];

It is also possible to insert multiple spaces, as you can see in the example.

import com.atlassian.confluence.spaces.SpaceManager
import com.atlassian.confluence.content.render.xhtml.DefaultConversionContext
import com.atlassian.confluence.pages.PageManager
import com.atlassian.confluence.xhtml.api.XhtmlContent;
import com.atlassian.sal.api.component.ComponentLocator
import com.atlassian.confluence.pages.Attachment
import org.apache.commons.lang3.StringUtils


def spaceManager = ComponentLocator.getComponent(SpaceManager);
def pageManager = ComponentLocator.getComponent(PageManager);
def xhtmlContent = ComponentLocator.getComponent(XhtmlContent);

def result = ["List of pages with at least one unknown attachment..."];
// Type in your space keys below, separte with commas, e.g. "DOCS", "DEV"
def spaceList = [""];



for (def spaceKey : spaceList) {
    def space = spaceManager.getSpace(spaceKey)
    def pages = pageManager.getPages(space, true);
    result.add("Working with space '${space.key} : ${}', found '${pages.size}' pages");


    for (def page : pages) {


        // def page = pageManager.getPage(50661666)
        def content = xhtmlContent.convertStorageToView(page.getBodyAsString(), new DefaultConversionContext(page.toPageContext()))
        if (StringUtils.containsIgnoreCase(content, "/unknown-attachment")) {
            result.add(" -- (${}) '${page.title}'");




String string = "";
for (String r : result)
    string += r + "<br>"
log.error string;
return string;

After inserting the code, you will get the following view in ScriptRunner, where you can also edit line 18 as described above:

Step 4:

Run this script in ScriptRunner. This may take a few minutes to a few hours (depending on the size of the blanks). After it runs through, check the Confluence logs on your server. The output that is generated will look like this:

Working with space 'DOCS : Documents', found '153' pages

-- (123456789) 'Infrastructure - Network'

-- (99999999999) 'Evaluation 2021'

The first line references the name of the range you defined earlier in line 18, and the total of all attachments found in that range (in our customer’s example, in total 153).

In the next lines, “–” is used to reference each “Unknown Attachment” by the PageID and the name of the attachment.

Step 5:

The next step is to access the individual Confluence pages with “Unknown Attachments” identified in the fourth step. To do this, first open a new tab in the browser and enter the following URL there. Replace “your confluence url” with your company’s Confluence URL and “xxxxxxx” with one of the PageIDs you determined in the previous step.


Step 6:

Access the pages that have been detected that way and replace the “Unknown Attachment” icons with the correct files needed for this purpose from your server.


Follow these six steps, and you too will be able to eliminate all “Unknown Attachment” icons on your Confluence instance.

In the described case study, our customer was extremely satisfied with the work and the quick solution of the problem by our Atlassian Consultant Victoria.

If you need a competent partner at your side as well, who can always help you quickly and effectively with all kinds of problems that may arise when working with the various Atlassian tools, Actonic is the right partner for you.

Build on the wealth of experience of our long-standing Atlassian consultants and get rid of all your problems with Atlassian topics through our Atlassian consulting. As Atlassian Solution Partner and Marketplace Vendor, we are the ideal contact for you!

Learn more about our Atlassian consulting service:

Contact us now via the contact box below for your personal Atlassian consulting quote:

Want to
know more?

Contact us to talk to our experts and have all your questions answered.

free offer

How useful was this post?

Click on a star to rate it!

Average rating 5 / 5. Vote count: 1

No votes so far! Be the first to rate this post.