BCCL Documentation
Index

Client Versions and Updates

BCCL consists of two components that must work together: the BCCL Business Central extension (the app installed in your BC environment) and the BCCL client executable (BCCL.EXE) that you download and run locally. This page explains where to get the client, how to check which version you are running, how client and extension versions relate to each other, and how to resolve the errors that appear when the client is out of date.

Where to Download the BCCL Client

The current BCCL command-line client is always published at:

https://www.hougaard.com/on-premises/BCCL

This is the authoritative download location. The page always carries the latest published build. You can also reach the download from the Download the BCCL Client link on the BCCL page inside Business Central.

Beta and pre-release builds, when available, are published in the beta area:

https://www.hougaard.com/on-premises/BCCL/beta/

Support may ask you to test with a beta client when a client-side defect has been identified. Because the client is a single self-contained executable, picking up a beta build only means replacing the file -- no reinstall is required.

The Client Does Not Update Itself

BCCL is distributed as a downloaded bundle that you unpack locally (for example into a downloads folder, or a folder such as C:\BCCL&#;). An installed copy stays at whatever version you downloaded. There is no automatic update mechanism.

This has a practical consequence for troubleshooting: before reporting unexpected command output or behaviour, re-download the client from the page above and re-run the same command. Unexpected or malformed output is commonly caused by running an older copy of the client.

If the Build You Need Is Not on the Page

The build number shown on the download page may occasionally lag behind a newer build that exists but has not yet been uploaded. If support has asked you to use a specific build, or you need a build newer than the one listed, open a support ticket and ask for it to be uploaded. The requested build is then published to the same page.

Checking Which Version You Are Running

Run the client without any arguments:

BCCL.EXE

The output displays the client version number. Always include this number when reporting an issue.

To find the version of the BC extension, open Extension Management in Business Central and look for the BCCL extension.

If you are unsure which copy of BCCL.EXE a script or scheduled task uses, check the path in the script or in the Task Scheduler action, then check that file's version. It is common for several copies to exist on one machine.

Client Version vs. Extension Version

The client executable and the Business Central extension carry version numbers in the same format (for example 3.23.0.374), but they do not have to be identical.

  • It is supported, and sometimes recommended by support, to run a newer client against an older extension. Example from a real case: client 3.23.0.374 was used while the BC extension stayed at 3.23.0.373.
  • The 3.x client is backward compatible with the 2.x BC extension, so the client can be upgraded on its own without touching the extension.
  • The 3.0 extension requires at least a 3.0 client. An older client against a newer extension produces the "Version mismatch" error described below.

Updating the Client Only

Updating the client means replacing the downloaded BCCL.EXE file. Nothing needs to change on the Business Central side: no app update, no re-deployment, no configuration change.

When support tells you to "use the EXE from this version", only the executable needs to be swapped:

  1. Stop any running BCCL service or scheduled job that uses the file.
  2. Download the requested build from the download page.
  3. Replace the existing BCCL.EXE with the new file.
  4. Start the service or re-run the command.

Remembered settings and the license registration are stored in isolated storage, not in the executable, so they survive the swap. If BCCL reports trial mode after replacing the executable, run BCCL.EXE --check and re-register if needed (see Registration).

Fixes Delivered by Client Updates

Some problems are fixed entirely on the client side and are resolved by updating BCCL.EXE alone:

Problem Fixed by
System.OverflowException: Value was either too large or too small for an Int32. when exporting tables with BigInteger/Int64 values to SQL (2.x clients) The 3.0 client
Verbose mode (-v) not showing the generated SQL statement on SQL errors Client build 3.23.0.374 or newer
Failures with very short-lived access tokens issued by the Entra ID tenant The bccl.exe from the BCCL3 beta, which handles short-lived tokens better (see Running Long or Unattended Transfers Reliably)

In each case the BC extension can remain at its current version.

Keeping Client and Extension in Sync

Whenever the BCCL Business Central extension is updated -- for example through a new app version from AppSource or an extension upgrade -- you should also re-download BCCL.EXE from the download page and update every copy you run. If the client falls behind the extension, operations such as GETDATA fail with the "Version mismatch" error.

A simple maintenance rule:

  1. Extension upgraded in Business Central → download the newest client.
  2. Replace BCCL.EXE on every machine, server and scheduled job that runs it.
  3. Run a quick test command (for example BCCL.EXE -t tasks) from each location.

Error: "Version mismatch"

Symptom

Running a data retrieval action such as GETDATA from the BCCL client fails with:

An error has occurred: Version mismatch (222 vs. 281), please update your BCCL client to match the version of the BCCL Business Central Extension installed.

Cause

The locally installed BCCL.EXE is older than the BCCL Business Central extension installed in the environment. The client and the extension must be on matching versions.

How to Read the Two Numbers

The two numbers in the message (222 and 281 in the example) are the internal client/extension protocol version numbers reported by the client and the extension respectively. They are not the extension's marketing version number (such as 3.23.0.371).

Do not try to match the numbers in the error message against the extension version string. Simply install the newest client.

Resolution

  1. Determine which version of BCCL.EXE is in use on the machine that produced the error (run it without arguments, or check the file properties of the executable).
  2. Download the newest BCCL.EXE from https://www.hougaard.com/on-premises/BCCL.
  3. Replace the existing BCCL.EXE with the downloaded file on every machine, server and scheduled job that runs the client.
  4. Re-run the failing operation.

Multiple Installations

The client is often deployed in more than one place: developer workstations, integration servers, scheduled tasks, and BCCL service agents. Every copy of BCCL.EXE must be updated. If one copy is missed, the error reappears the next time that copy runs, even though the others work.

Confirmed Environment

This behaviour was confirmed on BCCL extension version 3.23.0.371 running on Business Central 27.3. This is an example only, not a restriction -- the same error appears on any version combination where the client is older than the extension.

The version mismatch error is unrelated to the authentication error Cannot continue without a user for Business Central (-u --user) or authenticated with --auth. Fixing the client version does not fix a broken script layout, and vice versa. See Authentication Issues for that error.

Output Shows "BCCL.BigStringBuilder" Instead of Data

Symptom

Running a data-retrieval command from the command line, for example:

bccl -t getdata -s table=21

prints the single line:

BCCL.BigStringBuilder

instead of the table data.

Explanation

BCCL.BigStringBuilder is the name of an internal BCCL type. The output means the command has not rendered the result -- it is not an error message about the table, the table number, or your Business Central data.

Resolution

  1. Verify that you are running the latest version of BCCL. Run BCCL.EXE without arguments to see the version, and compare it with the build on the download page.
  2. If you are not on the latest version, download and reinstall the client from https://www.hougaard.com/on-premises/BCCL.
  3. Re-run the exact same command.

If the output is still BCCL.BigStringBuilder on the latest published version, contact support and include the command line you used and the BCCL version number. No specific build number is "the fix" -- the requirement is simply to run the latest published version.

Quick Reference

Question Answer
Where do I download the client? https://www.hougaard.com/on-premises/BCCL (beta: https://www.hougaard.com/on-premises/BCCL/beta/)
Does the client update itself? No. Re-download and replace the file.
How do I see my version? Run BCCL.EXE with no arguments.
Must client and extension versions be identical? No. A newer client with an older extension is supported. An older client with a newer extension fails with "Version mismatch".
What does "update the EXE" involve? Replace BCCL.EXE. No BC-side change.
Output is BCCL.BigStringBuilder Install the latest client and re-run.
"Version mismatch (n vs. m)" Install the newest client on every machine that runs BCCL.