BCCL Documentation
Index

Running Long or Unattended Transfers Reliably

Large table exports and SQL replication runs can take longer than an authentication token lives, and they often run unattended from a scheduler. This page describes how to configure BCCL so that such runs survive the whole operation, and explains the mid-transfer errors you see when they do not.

The Checklist

Apply these three rules, in this order, to any BCCL run that is long, scheduled, or unattended. Together they are the configuration recommended by hougaard.com support when transfers fail part-way through.

1. Use S2S Authentication, Not OAuth

Use --auth S2S for long or scheduled runs.

  • OAuth (device code flow) access stops working after a period predefined by the tenant administrators, and it cannot be renewed without a user interacting with a browser. This makes OAuth unsuitable for long-running or scheduled transfers.
  • S2S authenticates with client credentials, so BCCL is able to re-authenticate automatically while the operation is still running.

See Service-to-Service Authentication for setting up the Entra application.

2. Put Every Parameter on One Single Command Line

Supply the connection, authentication, task, format, mapping and SQL parameters together on one BCCL command line. Avoid the two-step pattern of first storing settings with --remember and then running a second, parameter-less task command.

If the credentials are not available to the getdata command itself, BCCL cannot renew the token mid-transfer. With the full set of parameters present, BCCL can request a fresh token while the transfer is running.

A generic example (placeholders only, quote the client secret):

BCCL -t getdata -s table=27 -o Item -m mappingItem.mapping.json --auth S2S --clientid <client-id> --clientsecret "<client-secret>" --tenantid <tenant-id> -w "https://api.businesscentral.dynamics.com/v2.0/<tenant-id>/<environment>/WS/<company>/Codeunit/bccl"

Parameters to include for S2S:

Parameter Value
--auth S2S Selects service-to-service authentication
--clientid Application (client) ID of the Entra app
--clientsecret Client secret value, in double quotes
--tenantid Entra tenant ID
-w Full BCCL web service URL for the target company

This is the recommended practice for any getdata run expected to last longer than the token lifetime, and it is the single-command form support recommends when intermittent connection errors appear against api.businesscentral.dynamics.com mid-transfer.

3. Run Tasks Sequentially

Run BCCL tasks one after another against the same Business Central environment rather than in parallel. Sequential execution on its own does not eliminate every intermittent connection message (see below), but it is part of the supported configuration.

About --remember and Concurrent Sessions

--remember stores the remembered settings per user on the machine where the command was run. Two consequences matter for long and unattended runs:

  • Settings from several separate --remember invocations do not accumulate. Only the parameters given on that one command line are stored. A script must never contain two or more --remember lines; combine them into one.
  • Because of the way the values are stored, --remember is unsuitable for parallel or concurrent BCCL sessions. Remembered values from one session can overwrite those used by another, so the wrong company or connection may be used. When running BCCL for multiple companies or any multiple concurrent invocations, do not use --remember; put all parameters on each individual command line. See Replicating Multiple Companies.

Token Lifetime Assumptions

BCCL's token handling during a long run works as follows:

Behaviour Value
Typical access token validity 1 hour (the lifetime reported by Entra ID when the token is issued)
Token renewal point (S2S only) When about 80% of the reported lifetime has elapsed, roughly 48 minutes for a 1-hour token
OAuth Never renewed; a new sign-in is required

Consequence: if the Entra ID (Azure AD) tenant is configured to issue very short-lived tokens, the token can expire before BCCL renews it. The operation then fails with

Unauthorized The credentials provided are incorrect

even when the authentication parameters are supplied on the command line as described above.

Remedy for short-lived tokens: the bccl.exe from the BCCL3 beta works better with short-lived tokens than the 2.x releases. Download it from:

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

The beta bccl.exe can be used in place of the existing executable for the affected getdata run. Only the executable needs to be replaced. See Client Versions and Updates.

"Unauthorized The credentials provided are incorrect" Mid-Transfer

Symptom

When pulling a large table (for example tens of thousands of records), getdata inserts records successfully for a while, showing progress lines such as

Sql table <name>, 1000 inserted, 0 updated
Sql table <name>, 1000 inserted, 0 updated

and then fails with

An error has occurred: Unauthorized The credentials provided are incorrect

The same error may repeat several times.

How to Read It

The error appears after a number of successful batches, not immediately. That points to token expiry during the transfer, not to wrong credentials. Credentials that were wrong would fail on the very first request.

Cause

The OAuth access token used for the Business Central connection expires during the transfer. If the credentials are not available to the getdata command itself, BCCL cannot renew the token mid-transfer.

Diagnostic Checklist

Work through these steps in order:

  1. Add all authentication parameters to the getdata command line (--auth S2S --clientid … --clientsecret "…" --tenantid …) so BCCL can renew the token during the transfer. See rule 2 of the checklist above.
  2. If the error persists, measure the time to failure. Note how many minutes elapse from the start of the transfer until the error appears, and compare this against the token lifetime configured in Entra ID.
  3. Check whether the tenant issues short-lived tokens. BCCL renews the S2S token at about 80% of its reported lifetime (see "Token Lifetime Assumptions" above). Very short-lived tokens can expire before the renewal.
  4. If tokens are short-lived, use the bccl.exe from the BCCL3 beta, which handles short-lived tokens better.

"No connection could be made because the target machine actively refused it"

Symptom

During a long-running getdata or SQL replication run against cloud Business Central, the console shows normal progress lines, for example

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)

after which the transfer resumes and continues to completion.

What It Is

  • The message originates from the Business Central cloud API endpoint, not from BCCL itself.
  • It appears intermittently. The same command may run without any errors on a retry.
  • It is not related to table size. It has been observed both on large tables (tens of thousands of records) and on very small tables (a few hundred records).
  • Running tasks sequentially rather than in parallel does not on its own eliminate the message.

Remedy

Apply the checklist above:

  1. Use S2S authentication instead of OAuth. OAuth stops working after a predefined period set by the tenant administrators, whereas BCCL with S2S is able to re-authenticate during the process.
  2. Do not split the run into two commands (one with --remember and a second with only task parameters). Put all parameters on a single BCCL command line.
  3. Run tasks sequentially.

Occasional No connection could be made ... messages may still be seen after this. The transfer normally continues afterwards; the checklist is the supported way to minimise them.

Putting It Together: A Scheduled Replication Line

A single, self-contained command suitable for Windows Task Scheduler or a .cmd script. Everything BCCL needs to authenticate, re-authenticate and write to SQL is on one line (placeholders only):

BCCL -t getdata -s table=17 "view=WHERE(Field2000000003=1({minutes(-2H)}..))" -f sql -o G_L_Entry -m mapping\G_L_Entry.mapping.json --auth S2S --clientid <client-id> --clientsecret "<client-secret>" --tenantid <tenant-id> -w "https://api.businesscentral.dynamics.com/v2.0/<tenant-id>/<environment>/WS/<company>/Codeunit/bccl" --sqlconnect "Server=<server>;Database=<database>;User ID=<user>;Password=<password>"

Keep the whole command on one unbroken line in a batch file; Windows executes each line separately, and a wrapped command is executed as fragments. See Common Issues.

Quick Reference

Symptom Points to Action
Unauthorized The credentials provided are incorrect after successful batches Token expired mid-transfer S2S + all parameters on one line; then check Entra token lifetime; beta exe for short-lived tokens
Same error immediately on the first request Wrong credentials See Authentication Issues
No connection could be made ... (api.businesscentral.dynamics.com:443) then transfer resumes Intermittent cloud endpoint refusal S2S + single command line + sequential runs; occasional messages are expected
Long OAuth run stops working part-way Tenant-defined OAuth expiry Switch to S2S