When the BizFinx Preparation Tool Will Not Work: A Diagnosis by Symptom

Almost every BizFinx Preparation Tool failure comes down to one of four things: macros are switched off, the Office add-in plumbing is broken, the tool is already running invisibly, or your machine does not meet the current system requirements. Work out which one you have and the fix takes minutes.

Raffles Corporate Services works with a panel of experienced Singapore law firms who offer cost-effective and efficient legal service and advice. This article is general information only and is not legal advice.

The tool is not a website. It is an add-in that bolts itself onto Microsoft Excel on a Windows machine, which means it depends on a stack of Microsoft components that most people never think about: the Visual Studio Tools for Office runtime, the Primary Interop Assemblies, Visual Basic for Applications, the .NET Framework and, on some builds, the Visual C++ redistributables. When any one of those is missing, disabled or damaged, the tool does not announce the real problem. It just sits there.

That is why the usual approach of reinstalling the tool over and over rarely helps. Diagnose first.

First, rule out the two things that are not really faults

Before you troubleshoot anything, check two facts. They account for a surprising share of the calls we get in filing season.

You are on the wrong version. ACRA maintains version 4.0 of the Preparation Tool for financial statements prepared under the revised XBRL filing requirements. Version 3.4.1 is kept alive for a narrower purpose: correcting errors in files that were originally prepared on version 3.4 or earlier, which is a Notice of Error situation. If you are preparing a fresh set of accounts on 3.4.1 you are using the wrong tool, and the symptoms will look like faults. To check what you have open, go to the Filing Information tab and look under Details of XBRL file.

Your Office licence is not one the tool supports. The Preparation Tool runs against desktop Office: Office 2013, 2016, 2019, 2021 and the desktop versions of Office 365. It does not run on Office 365 Business Essentials, and it does not run on Office Online. If your company moved to a web-only Office plan, no amount of repairing will make the add-in appear, because there is no desktop Excel for it to attach to.

Version 4.0 also needs Microsoft .NET Framework 4.8.0 or later, Windows 8.1, Windows 10 from version 1607, or Windows 11, and roughly 1.2GB of disk space. The Multi-upload Tool needs the same .NET version but far less disk.

Symptom: the Create and Open buttons are there, but clicking does nothing

The add-in has loaded far enough to draw its ribbon, but the code behind the buttons cannot execute. Nine times out of ten that is macro security. Excel has decided the tool’s code is untrusted and has silently blocked it.

The order of attack:

1. Enable macros in Excel’s Trust Centre for the tool.
2. If that does not do it, run an Office repair. A repair rebuilds the components Office exposes to add-ins without touching your files.
3. If it still does nothing, apply ACRA’s current Preparation Tool patch, which is published alongside the tool download.

Do them in that order. Repairing Office first when the real problem is a macro setting simply wastes twenty minutes.

Symptom: the Create and Open buttons are not there at all

This is a different failure. The ribbon never appeared, which means the add-in did not load, which usually means a component it depends on is missing rather than blocked.

The most common missing piece is Visual Basic for Applications. VBA is an optional Office component and corporate IT builds routinely leave it out, either to reduce the attack surface or simply because nobody ticked the box. Add VBA through the Office installer, then enable macros, then restart Excel.

If VBA is present and the buttons are still absent, work down the dependency chain: repair the Primary Interop Assemblies, then the Visual Studio Tools for Office runtime, then Office itself.

Symptom: an “MS Office Document Customisation” message appears

Treat this message as a diagnosis, not an error. It is Office telling you that a document-level customisation, which is exactly what the Preparation Tool is, failed to initialise. The tool is installed correctly. The bridge between it and Excel is broken.

That bridge is made of two parts, and both can be repaired independently:

• the Primary Interop Assemblies, which let .NET code talk to Office
• the Visual Studio Tools for Office runtime, which actually hosts the customisation

Repair the interop assemblies first, then the VSTO runtime, then Office. If the buttons were also missing, add the Visual Basic for Applications step above before any of this.

Symptom: “the BizFinx preparation tool is already running”

Take the message literally. The tool permits exactly one set of templates open at a time, and it enforces that by checking whether its Excel process is alive. If Excel crashed earlier and left an orphaned process behind, the check fails even though nothing is visible on screen.

1. Close every Excel window.
2. Open Task Manager, go to Processes, and end every EXCEL.EXE process you find.
3. Reopen the Preparation Tool.

If the message survives that, the cause is permissions rather than processes. The tool writes to its own installation folder, and on a locked-down corporate laptop the logged-in user often has read and execute rights but not write. Test it directly: create a new text file inside the installation folder, then delete it. If either action is refused, you do not have full control of the folder and your IT team needs to grant it. For version 3 installations that folder is C:\Acra Preparation Tool v3.

Symptom: it says .NET Framework is not installed, but it is

This is a damaged installation rather than a missing one. Open Control Panel, then Programs and Features, find the Microsoft .NET Framework entry, right-click it and choose Repair. Reinstall the Preparation Tool afterwards.

Check the version number while you are there. Version 4.0 of the tool expects .NET Framework 4.8.0 or later. Older guidance written for the version 3 series refers to 4.7.2, which is no longer sufficient if you have moved up to version 4.0.

Symptom: a GEN-02 error while answering the scoping questions

GEN-02 surfaces early, while the tool is still working out which sections of the taxonomy your company has to complete, and the message itself tells you nothing. It is the one fault that genuinely needs a sequence rather than a single fix, because several different underlying causes produce the same code.

Work through it in this order, testing after each stage:

1. Bring the machine current. Install outstanding Windows updates, repair Microsoft Office, and install the VSTO runtime.
2. Replace the text control components. ACRA publishes a replacement set for these; they are copied into the tool’s installation folder, overwriting what is there.
3. Install the Visual C++ 2013 redistributables, both the 32-bit and 64-bit packages, then restart.
4. Apply the current Preparation Tool patch.
5. If it still fails, open the XBRL file directly from the installation folder rather than from wherever you saved it.

If you exhaust the sequence, ACRA will want three things before it can help: a screenshot of the error, the tool’s log file from its own iFile\Conf\Log directory, and the source document that triggers the failure. Gather those before you raise the enquiry rather than after.

Symptom: your last saved Excel file opens instead of the tool

Nothing is broken here. Windows has associated the tool’s template with plain Excel, so double-clicking launches Excel with your most recent workbook instead of launching the add-in. Correcting the file extension association resolves it. An Office repair fixes the stubborn cases.

The quick reference

What actually goes wrong in practice

The technical faults are not the expensive part. The expensive part is when they happen.

Companies tend to open the Preparation Tool for the first time in the week the annual return is due. That is the worst possible moment to discover that VBA was stripped out of the corporate Office build, or that you need administrator rights you do not have, or that the finance laptop is on a web-only Office plan. Each of those needs somebody else to act, and IT departments do not turn requests around in an afternoon just because your filing deadline is Friday.

Filing your financial statements in XBRL is part of the annual return obligation under Section 197 of the Companies Act 1967. A tool that will not open is not a defence, and late lodgement penalties do not care why the filing was late.

The fix is unglamorous. Open the tool once, on the right machine, a month before you need it. Create a dummy file. Close it. If it works, you have removed the entire risk category. If it does not, you have four weeks to sort it out instead of four days.

It is also worth knowing when you do not need the tool at all. Companies using approved accounting software can generate the XBRL file directly, and the Multi-upload Tool exists precisely so that firms filing for several entities are not opening and closing a spreadsheet add-in all day. Our guide to XBRL filing with ACRA covers who has to file in XBRL and which exemptions apply, and our walkthrough of filing the annual return in Bizfile shows where the XBRL file slots into the wider filing.

Frequently asked questions

Can I run the BizFinx Preparation Tool on a Mac?
No. The tool is a Windows application that attaches to desktop Microsoft Excel and depends on Windows components such as the .NET Framework and the VSTO runtime. Running Windows in a virtual machine on a Mac can work, provided the virtual machine itself meets the published hardware and software requirements.

Which version of the Preparation Tool should I be using?
Version 4.0 for financial statements prepared under the revised XBRL filing requirements. Version 3.4.1 is retained only for correcting errors in files originally prepared on version 3.4 or earlier, which is a Notice of Error scenario. Check your version on the Filing Information tab, under Details of XBRL file.

Why does the tool work on my colleague’s laptop but not mine?
Because the difference is almost never the tool. It is usually the Office build, the presence or absence of Visual Basic for Applications, macro security settings applied by your IT policy, or whether you have write access to the tool’s installation folder. Compare those four things before reinstalling anything.

Do I need administrator rights to install it?
You will generally need administrator rights to install the tool, the .NET Framework, the VSTO runtime and the Visual C++ redistributables. You also need full read, write and execute access to the tool’s installation folder afterwards, which is a separate permission and the one most often missed on corporate machines.

My filing is due this week and the tool still will not open. What now?
Stop troubleshooting and change route. Ask your accountant or corporate secretary whether they can generate the XBRL file from approved accounting software on their own system. That removes your machine from the critical path entirely and is far faster than escalating an IT ticket against a deadline.

Do not let a spreadsheet add-in decide your filing date

Every year we see otherwise well-run companies miss a deadline because a piece of Microsoft plumbing failed at the wrong moment. The underlying accounts were finished. The approval was done. The tool would not open.

Raffles Corporate Services prepares and files XBRL financial statements for companies across a wide range of sizes and reporting frameworks, on our own systems and to our own schedule. If your last filing season involved a week of fighting an Excel add-in, that is a problem you can simply hand over.

You can reach us through Raffles Corporate Services, or read more on Singapore corporate secretarial practice at Singapore Secretary Services.

— The Editorial Team, Raffles Corporate Services