Common Issues

This page covers the most frequently encountered problems when working with BCCL, along with their causes and solutions. If your issue is specifically related to authentication, see Authentication Issues for dedicated coverage of that topic.

Several problem areas have their own detailed pages. Use this index to jump straight to them:

Symptom or error text	See
`Version mismatch (... vs. ...)`, output shows `BCCL.BigStringBuilder`, where to download a newer or beta client	Client Versions and Updates
`Trial version detected`, `Cannot contact hougaard.com for license verification`, license registered on the wrong tenant, moving a license to another tenant	License and Registration Issues
`Sorry, the current permissions prevented the action`	Permission Errors
`Unknown or wrong SQL table`, `Incorrect syntax near`, `String or binary data would be truncated`, `System.OverflowException`, nothing written to SQL	SQL Output Issues
`... must have a value in ... It cannot be zero or empty` on PUTDATA	Import (PUTDATA) Errors
`Unauthorized The credentials provided are incorrect` or `target machine actively refused it` part-way through a long transfer	Running Long or Unattended Transfers Reliably
Slow or intermittently failing exports	Export Performance and Intermittent Export Errors
`A valid license not found for ...` and other errors raised by third-party apps	Identifying Which App Raised an Error
Reading verbose (`-v`) output	Diagnosing with Verbose Mode
Questions rather than errors	Frequently Asked Questions

Connection Issues

"Could not connect" or Connection Refused

Cause: BCCL cannot reach the Business Central web service endpoint.

Solutions:

Verify the web service URL (--wsurl or -w) is correct and includes the full OData path.
Confirm that Business Central is running and accessible from the machine where BCCL is installed.
Check network connectivity -- can you reach the BC server from a browser on the same machine?
If you are behind a firewall or proxy, ensure that outbound HTTPS traffic to the BC server is allowed.
For on-premises installations, verify that the BC web server instance is started and the OData endpoint is enabled.

SSL/TLS Errors

Cause: The HTTPS certificate on the BC server is invalid, expired, or not trusted.

Solutions:

Ensure the server's SSL certificate is valid and not expired.
For on-premises environments with self-signed certificates, install the certificate in the machine's Trusted Root store.
Verify that the certificate's subject name matches the URL you are using.

Timeout Errors

Cause: The operation takes longer than the allowed time, usually due to network latency or large data volumes.

Solutions:

Reduce the page size (-z) to transfer fewer records per request.
Check network latency between the BCCL machine and the BC server.
For very large exports, consider using SQL output format, which streams data rather than buffering it.
Verify that the BC server is not under heavy load.

"No connection could be made because the target machine actively refused it" During a Long Transfer

Symptom: During a long-running getdata or SQL replication run against cloud Business Central, the console shows normal progress lines such as Sql table [TableName], 0 inserted, 1000 updated, then one or more lines of:

An error has occurred: No connection could be made because the target machine actively refused it. [<ip>]:443 (api.businesscentral.dynamics.com:443)

The transfer then resumes and continues to completion.

Cause: The message originates from the Business Central cloud API endpoint, not from BCCL, and appears intermittently. The same command may run without any errors on a retry. It is not related to table size (it has been observed on tables with tens of thousands of records and on tables with a few hundred), and running tasks sequentially instead of in parallel does not eliminate it on its own.

Solutions:

Use S2S authentication instead of OAuth. OAuth access stops working after a period predefined by the tenant administrators, whereas BCCL with S2S can re-authenticate while the run is in progress.
Do not split the run into two commands (one --remember command followed by a task-only command). Put all parameters, authentication and task, on a single BCCL command line.
See Running Long or Unattended Transfers Reliably and Service-to-Service Authentication.

"Cannot continue without a URL for Business Central (-w --wsurl)"

Symptom: Every BCCL -t getdata ... line in a batch file fails with:

An error has occurred: Cannot continue without a URL for Business Central (-w --wsurl)

often preceded by Windows messages such as '"<fragment>"' is not recognized as an internal or external command, operable program or batch file.

Cause: The BCCL --remember ... command in the batch file has been wrapped over several lines. Windows executes each line separately, so the continuation fragments (typically the client secret value or the SQL connection string) are run as commands, and the -w value never reaches BCCL and is not stored.

Solutions:

Open the batch file in a plain text editor and join the whole --remember command back onto one single, unbroken line. Editors, e-mail clients, and word processors that soft-wrap long lines are a common source of this problem.
Enclose values containing spaces, semicolons, or special characters (client secret, SQL connection string, web service URL with a company name) in double quotes.
See "Batch File Rules" in Command Reference for a single-line example.

Data Format Issues

"Invalid JSON" or JSON Parse Errors

Cause: The input file is not valid JSON or is not structured as a JSON array.

Solutions:

Validate your JSON file with a JSON linter or editor.
BCCL expects a JSON array of objects at the top level: [{"Field1": "value"}, ...].
Check for trailing commas, mismatched brackets, or encoding issues.
Ensure the file is saved as UTF-8 without a BOM.

CSV Parsing Errors

Cause: The CSV file structure does not match BCCL's expectations.

Solutions:

Verify the delimiter matches what you specified with -l. The default is comma (,).
Check the quote character (-c). The default is double quote (").
Ensure the file is encoded as UTF-8. BCCL does not support legacy encodings like ANSI or Latin-1.
If your data contains literal quote characters, use the --ignorequotes (-q) flag.
Confirm that every row has the same number of columns as the header row.

XML Errors

Cause: The XML file is malformed or the record path does not match the document structure.

Solutions:

Verify the record element path (-r parameter) points to the correct XML element.
Ensure the XML file is well-formed (properly nested tags, correct encoding declaration).
Use an XML editor or validator to check the file before import.
The record path should identify the repeating element that represents individual records.

Excel Issues

Cause: The Excel file cannot be read or written correctly.

Solutions:

Close Microsoft Excel before running BCCL. Excel locks files and prevents other processes from accessing them.
Use the .xlsx format, not .xls. BCCL does not support the legacy Excel 97-2003 format.
Verify the sheet name (-x) matches exactly, including capitalization and spaces.
When specifying a data range (-y), use two dots as the separator, not a colon. For example: A1..H100 instead of A1:H100.
Ensure the data range covers all rows and columns you want to include.

Mapping Issues

"Field not found"

Cause: A FieldNo in the mapping file does not correspond to a valid field in the BC table.

Solutions:

Verify that every FieldNo in your mapping.json matches an actual field number in the target table.
Field numbers can differ between BC versions or between companies with custom extensions. Regenerate the mapping if the table schema has changed.
Use the Mapping Builder in the Request Builder to generate a fresh mapping from the current table definition.

"MappedName mismatch"

Cause: The column headers in your input file do not match the MappedName values in the mapping file.

Solutions:

Open the mapping.json file and check the MappedName for each field.
CSV column headers must match MappedName values exactly, including case.
JSON property names must also match MappedName values.
If you renamed columns in the Mapping Builder, ensure your input files use those renamed values.

Generating a Fresh Mapping

If your mapping file is out of date or corrupted, generate a new one:

BCCL.EXE -t mapping -s table=18 -o mapping.json

Replace 18 with your table number. This creates a mapping file with all fields using their default BC names.

"Field ... is obsoleted" When Running GETDATA

Symptom: A GETDATA run (from the command line or as a Get Data Service Task) fails with an error of the form:

An error has occurred: Field <Field Name> (<Field No.>) of table <Table Name> (<Table No.>) is obsoleted, reason: <Microsoft's obsolete reason>.

For example:

An error has occurred: Field IRS 1099 Amount (10021) of table Purchase Header (38) is obsoleted, reason: Moved to IRS Forms App.

Cause: The mapping file used by the task still refers to a field that Microsoft has marked obsolete in the Business Central base application. Fields can be removed, renamed, or moved into a separate app (as with the IRS 1099 fields moving to the IRS Forms app). BCCL cannot read an obsoleted field.

Solutions:

Remove the obsoleted field(s) from the mapping file(s) used by the task, then re-run.
There is no graceful way around this: BCCL has no setting, switch, or "skip obsoleted fields" option. Editing the mapping is the only option.
Each error reports one field at a time. After removing one obsoleted field the task may fail on the next one; repeat until the task completes.
Review your mapping files after every major Business Central upgrade. See "Maintaining Mapping Files Across Upgrades" in Mapping Files.

This behaviour is not version-specific. It was reported on Business Central 27 and 28 (US, Platform 28.0.x, Application 28.2.x) with BCCL app version 3, and it occurs on any BC version where a mapped field has been obsoleted.

"You cannot open record ... from a RecordRef data type when you are using target Cloud"

Symptom: Building a mapping for, or reading from, a table fails with:

You cannot open record 2000000095 from a RecordRef data type when you are using target Cloud.

Table 2000000095 is an example; the same error can appear for other table numbers.

Cause: The error is raised by the Business Central platform, not by BCCL. Certain system and virtual tables are restricted by Microsoft, and the platform refuses to open them through a RecordRef when the extension target is Cloud (SaaS). BCCL reads and writes data dynamically through RecordRef and FieldRef, so any table the platform will not open via RecordRef cannot be reached by BCCL at all.

Solutions:

There is no BCCL setting, permission, configuration, or workaround that bypasses this restriction. It is enforced by the runtime on the Cloud target. Some tables are restricted by Microsoft, and there is no way around it.
This is not a bug in BCCL, and there is nothing to fix in the app or in the mapping file.
The usual alternative is to have AL code in an extension read the restricted table using a direct Record variable of that type (where the platform allows it), copy the needed rows into a normal, non-virtual table, and build the BCCL mapping against that normal table instead. Whether a direct Record variable is allowed for a given table is also decided by the platform, not by BCCL.

Observed on BCCL app version 3.23.0.372 and Business Central 28.5, but the limitation follows Microsoft's platform restrictions and is not specific to a BCCL version.

SQL Issues

Connection String Errors

Cause: The SQL Server connection string is incorrect or the SQL Server is unreachable.

Solutions:

Verify the server name, database name, and authentication details in the connection string.
For Windows authentication: Server=myserver;Database=mydb;Trusted_Connection=True;
For SQL authentication: Server=myserver;Database=mydb;User Id=myuser;Password=mypassword;
Ensure the SQL Server allows remote connections and the firewall permits access on the configured port.

Type Conversion Errors

Cause: A BC field value cannot be converted to the target SQL column type.

Solutions:

Review the mapping file for fields with incompatible type mappings.
Common issue: BC date fields with empty values (0D). Use --sqlzerodate to specify a replacement date (default is 1900-01-01).
Ensure numeric fields in BC are not being mapped to string columns in SQL, or vice versa.

"System.OverflowException: Value was either too large or too small for an Int32"

Symptom: A getdata run with SQL output aborts with an unhandled exception. The stack trace contains lines such as:

Unhandled exception. System.OverflowException: Value was either too large or too small for an Int32.
   at System.Convert.ToInt32(Int64 value)
   at Newtonsoft.Json.Linq.JToken.op_Explicit(JToken value)
   at BCCL.Program.GetValue(JToken record, String column)
   at BCCL.Program.ImportIntoSql(...)

A typical command shape that triggers it:

BCCL -t getdata -s table=36 -o Sales_Header -m Sales_Header.mapping.json

Cause: The table contains BigInteger (Int64) fields whose values exceed the Int32 range. In BCCL 2.x clients these fields can be handled internally as Int32, so the conversion overflows. This is known to happen with fields added by the Shopify Connector, both on standard tables it extends (for example Sales Header, table 36) and on its own tables (for example table 30141 Shpfy Return Line and table 30142 Shpfy Refund Header). It can surface after a Business Central version upgrade (reported on BC 26.1) even though the SQL table was recreated and the mapping file regenerated; recreating the table and regenerating the mapping does not fix it. Having the SQL columns correctly declared as bigint does not resolve it in older clients either.

Solutions (in the order support gives them):

Preferred: upgrade to the BCCL 3.0 client executable. The 3.0 client fixes the data-type handling, and the same export completes successfully after switching. The 3.x client is backward compatible with the 2.x BC extension, so you can replace the executable on its own without touching the extension. If needed, a beta client is available from the on-premises beta download area (https://www.hougaard.com/on-premises/BCCL/beta/).
Workaround if you cannot upgrade and do not need the fields: remove the mapping entries for the offending BigInteger fields from the mapping file. Only fields present in the mapping are exported, so removing them avoids the conversion.
There is no way to "correct" the mapping so that the value converts. Manual mapping edits can only exclude the fields; the actual fix is the 3.0 client.

Before troubleshooting, run BCCL.EXE with no arguments to confirm which client version you are on. Note that no category of BC tables is blocked from BCCL: Shopify and other standard-app tables are readable like any other table, and an error on such a table indicates a data-type or client-version problem, not an access restriction. See also SQL Output Issues.

Duplicate Key Violations

Cause: The target SQL table has a unique constraint and BCCL is inserting a record that already exists.

Solutions:

By default, BCCL performs an upsert (insert or update). If you are seeing duplicate key errors, the SQL table's constraints may not align with what BCCL expects.
Use --sqlprecommand to truncate or clear the target table before import: --sqlprecommand "TRUNCATE TABLE staging_customers".
Verify that the primary key columns in the SQL table match the BC table's primary key structure.

Other SQL Output Errors

The following SQL-side errors have their own entries in SQL Output Issues:

Unknown or wrong SQL table <name>
Cannot update table ... in SQL, error: Incorrect syntax near '=' (or near ',')
String or binary data would be truncated
No error, but nothing is written to SQL and JSON is printed on the console (the -o parameter is missing)

Paging Issues

Large Datasets Are Slow

Cause: The default page size may not be optimal for your data and network conditions.

Solutions:

Reduce the page size (-z) if individual requests are timing out.
Increase the page size if the network is fast but throughput is low due to too many round trips.
For very large datasets, use SQL output format instead of file output. SQL output streams records directly to the database without buffering the entire result set in memory.

Out of Memory

Cause: The dataset is too large to hold in memory at once.

Solutions:

Use SQL output format, which streams data incrementally.
Reduce the page size to process smaller chunks.
Split the operation into multiple runs using filters (for example, export by date range or by letter range).

Registration Issues

"Trial version detected"

Symptom: Commands print:

Trial version detected, data transfers are limited to 100 records upload and 50000 bytes download.

Cause: Either BCCL on this machine has never been registered, or the license has expired. An installation that has been working normally for a long time (even more than a year) and then suddenly stops updating and reports itself as a trial is the typical sign of an expired license. This is not a corruption, reinstall, or configuration problem.

Solutions:

If this is a new machine (for example a new production server), register the instance:

  BCCL.EXE --register <license-key> --tenantid <tenant-id>

Put this line first in your batch file so that registration is verified on every run.

If BCCL used to run licensed on this machine, contact support@hougaard.com to have the license status checked and renewed. Mention that the message Trial version detected appeared and roughly when BCCL stopped updating.
Check the status with BCCL.EXE --check.
See License and Registration Issues for details.

"Key expired"

Cause: Your license key is past its validity period.

Solutions:

Contact hougaard.com for license renewal.
Check your license status with BCCL.EXE --check.

"Cannot contact hougaard.com for license verification"

Symptom:

Cannot contact hougaard.com for license verification (Object reference not set to an instance of an object.)
Registration failed, please use --register with a valid key

Cause: A firewall or proxy on the server or network blocks access to the license check host check.hougaardlicense.com.

Solution: Ping the host and open it in a browser on the server itself (a successful ping alone is not proof), have the network administrators allow outbound access, then re-run --register. The full diagnostic procedure is in License and Registration Issues.

"Registration failed" on the Intended Tenant

Cause: The license key was already registered against a different (wrong) tenant ID. A key is bound to the tenant it was registered against and cannot simply be re-registered on another tenant by the end user.

Solution: The registration must be reset by hougaard.com support. Send the license key, the incorrect tenant ID, and the correct tenant ID to support, wait for confirmation, then run --register again with the correct tenant ID. See License and Registration Issues.

Command-Line Mode Issues

A Command-Line Task Starts but Never Finishes

Symptom: A task started from the command line, for example:

BCCL -t getdata -s table=5050 -o "contact" -f sql -m "<BCCL install folder>\Mappings\<name>.mapping.json"

prints the banner and then keeps the prompt occupied without ever ending. The output looks like the service host starting up:

BCCL <version>
info: Microsoft.Hosting.Lifetime[0] Application started. Press Ctrl+C to shut down.
info: Microsoft.Hosting.Lifetime[0] Hosting environment: Production
info: Microsoft.Hosting.Lifetime[0] Content root path: <BCCL install folder>

Cause: A bccl_service.json file is present in the BCCL folder (the folder shown as Content root path). When this file exists, BCCL starts in service mode instead of executing the task given on the command line. The command-line parameters are not run, and the process stays alive waiting to be shut down with Ctrl+C. The command syntax itself is not the problem.

Solutions:

Remove bccl_service.json from the BCCL folder and run the command again. If you need to keep the service configuration for later, move or rename the file out of the folder, and put it back when you want to run BCCL as a service again.
If the same machine must act as a service host and also run ad-hoc commands, keep two copies of BCCL.EXE in two folders: one with bccl_service.json and one without. See "How BCCL Decides Between Service Mode and Command-Line Mode" in Service Installation Overview.

Confirmed on BCCL 3.23.0.372.

Task Name Typos

The export task is spelled getdata. A misspelling such as -t getdate is not a valid task. Valid -t values are: getdata, putdata, deletedata, deleteall, massupdate, runcodeunit, changelog, tables, mapping, tasks, download, upload. Check the -t value first when a command behaves unexpectedly.

File Storage Issues

FTP/SFTP Connection Failures

Cause: Incorrect credentials or network settings for remote file storage.

Solutions:

Verify the server address, port, username, and password in --filestoragesettings.
For SFTP, the default port is 22. For FTP/FTPS, the default port is 21.
Check that the remote path exists and the user has write permissions.
For FTPS, ensure the server's certificate is trusted.

"File locked" Errors

Cause: Another application has the file open exclusively.

Solutions:

Close Microsoft Excel, text editors, or other applications that may have the file open.
If a previous BCCL run was interrupted, the file may still be locked. Wait a moment and retry.

"Permission denied"

Cause: The user running BCCL does not have write access to the output directory.

Solutions:

Verify that the output directory exists and the current user has write permissions.
When running as a Windows service, the service account needs appropriate file system permissions.
For network paths (UNC), ensure the service account has access to the network share.

General Troubleshooting Tips

Enable verbose mode (-v) to see detailed diagnostic output for any operation. See Diagnosing with Verbose Mode.
Check the BCCL version by running BCCL.EXE without any arguments. Include the version number when reporting issues.
Update the client first when you hit an unhandled .NET exception (for example System.OverflowException). Check your client version, then try the current BCCL 3.x client before investigating further. Unhandled runtime exceptions are frequently fixed by a client update, and the 3.x client works against the 2.x BC extension. See Client Versions and Updates.
Check the task name. -t getdata, not getdate. See "Task Name Typos" above.
Start simple. If a complex command fails, strip it down to the minimum parameters and add settings back one at a time.
Validate input files independently before using them with BCCL.

Common Issues

Connection Issues

"Could not connect" or Connection Refused

SSL/TLS Errors

Timeout Errors

"No connection could be made because the target machine actively refused it" During a Long Transfer

"Cannot continue without a URL for Business Central (-w --wsurl)"

Data Format Issues

"Invalid JSON" or JSON Parse Errors

CSV Parsing Errors

XML Errors

Excel Issues

Mapping Issues

"Field not found"

"MappedName mismatch"

Generating a Fresh Mapping

"Field ... is obsoleted" When Running GETDATA

"You cannot open record ... from a RecordRef data type when you are using target Cloud"

SQL Issues

Connection String Errors

Type Conversion Errors

"System.OverflowException: Value was either too large or too small for an Int32"

Duplicate Key Violations

Other SQL Output Errors

Paging Issues

Large Datasets Are Slow

Out of Memory

Registration Issues

"Trial version detected"

"Key expired"

"Cannot contact hougaard.com for license verification"

"Registration failed" on the Intended Tenant

Command-Line Mode Issues

A Command-Line Task Starts but Never Finishes

Task Name Typos

File Storage Issues

FTP/SFTP Connection Failures

"File locked" Errors

"Permission denied"

General Troubleshooting Tips

Related Topics

Send Feedback