BCCL Documentation
Index

Diagnosing with Verbose Mode

Verbose mode is the first step in troubleshooting any BCCL error. Adding the -v parameter to a command makes BCCL show what it is doing while it runs: the request it sends to Business Central, the field mapping in effect, whether a SQL pre-command was processed, and the exact values and sizes of every parameter in a failing SQL statement. This page explains how to enable verbose mode, what the output contains, and how to read it.

Enabling Verbose Mode

Add -v (long form --verbose) to the same command line as your other BCCL parameters. No other syntax, switch or log level exists -- -v is the only diagnostic option.

bccl -t getdata -s table=<tableno> -f sql -m "<mapping>.map.json" -o "bc.[<TableName>]" -v

Verbose mode has two effects:

  • The BCCL client prints detailed diagnostic output to the console.
  • The request sent to Business Central includes "Verbose": true, so the BC extension returns additional detail as well.

Use -v whenever a BCCL command fails, errors intermittently, or behaves unexpectedly. Support will normally ask for the complete verbose output when investigating an issue, especially a SQL error.

Capturing the Output to a File

Verbose output can be long. Redirect it to a file so you can review it and attach it to a support request:

Windows Command Prompt:

BCCL.EXE -t getdata -s table=18 -f sql -o Customer -m customer.mapping.json -v > bccl_verbose.txt 2>&1

PowerShell:

& BCCL.EXE -t getdata -s table=18 -f sql -o Customer -m customer.mapping.json -v 2>&1 | Out-File bccl_verbose.txt

Remove environment-identifying details (tenant IDs, client secrets, connection strings) before sending the file.

What the Verbose Output Contains

The output appears in the following order.

1. License Verification

Verifying your BCCL license ...
License OK

If the license has expired or is not registered, this section shows the trial or expiry message instead. See Registration.

2. The Full JSON Request Sent to Business Central

BCCL prints the complete request object. The properties you will see include:

Property Meaning
Task The task being executed, for example getdata
Format The data format, for example sql
Binary Whether binary fields are included (-b)
Header Whether CSV output includes a header row (-h)
Delimiter The CSV delimiter (-l)
QuoteChar The CSV quote character (-c)
PagingID The identifier used for paging across requests
PageSize Records per page (-z)
DelayedInsert Whether the delayed insert pattern is active (-d)
Verbose true when -v is used
SqlZeroDate The substitute for blank dates in SQL output
Settings The -s settings, for example "table": "18" and any view= filter
BuildNo The client build number
Mapping The complete field mapping array
ValidateOnInsert / ValidateOnModify Table-level validation settings

Each entry in the Mapping array contains FieldNo, FieldName, MappedName, Validate and, for fields with a table relation, optionally CreateRelatedStub.

3. SQL PreCommand Confirmation

If --sqlprecommand is specified, verbose output tells you whether it was processed:

SQL PreCommand Result=-1

or, if it failed:

Could not execut SQL PreCommand, error: <SQL Server message>

If neither line appears, the pre-command was not executed. This is the recommended way to confirm that a pre-command such as SET ANSI_WARNINGS OFF or TRUNCATE TABLE ... actually reached SQL Server.

4. Authentication and Web Service Call

For OAuth and S2S, BCCL reports the token request. It then reports the size of the primary result and how long the web service call took:

Requesting OAuth token ...
Primary result length: 184532, web service call duration: 00:00:03.2145678

5. SQL Error Details (per failing row)

When a SQL insert or update fails, BCCL prints one error block per failing row:

Index #0
Message: String or binary data would be truncated.
LineNumber: 1
Source: Core .Net SqlClient Data Provider
Procedure:

Immediately after the error block, BCCL prints every parameter of the failing row with the value it tried to send and the SQL data type and size it inferred for that value:

Parameter Code0 = <value> (NVarChar Size 3)
Parameter No_1 = C00010 (NVarChar Size 6)
Parameter Name2 = Sample Customer Name That Is Longer Than The Column (NVarChar Size 52)
Parameter Address3 = 12 Example Street (NVarChar Size 17)

From client build 3.23.0.374, the error message also includes the actual generated SQL statement, which identifies the offending column directly. Earlier builds show only the SQL Server message and the parameter list.

6. Failing Record Content (PUTDATA)

On an import that fails, verbose output prints a Content: line containing the JSON payload of the record that was being processed. This shows exactly which fields and values BCCL sent to Business Central for that record.

7. Closing Summary per Table

At the end of a SQL transfer, BCCL prints one summary line per target table:

Sql table bc.[Customer], 0 inserted, 0 updated

or, with a company-qualified table name:

Sql table [<Company>$Customer], 1000 inserted, 0 updated

A summary of 0 inserted, 0 updated after errors means no rows were written.

Sample Verbose Output

The following is a generalised, anonymised example of a SQL export that fails on one row because a value is wider than the target column:

BCCL 3.23.0.374
Verifying your BCCL license ...
License OK
Request:
{
  "Task": "getdata",
  "Format": "sql",
  "Binary": false,
  "Header": true,
  "Delimiter": ",",
  "QuoteChar": "\"",
  "PagingID": "<guid>",
  "PageSize": 1000,
  "DelayedInsert": false,
  "Verbose": true,
  "SqlZeroDate": "1900-01-01",
  "Settings": { "table": "18" },
  "BuildNo": 281,
  "Mapping": [
    { "FieldNo": 1, "FieldName": "No.", "MappedName": "No_", "Validate": true },
    { "FieldNo": 2, "FieldName": "Name", "MappedName": "Name", "Validate": true },
    { "FieldNo": 21, "FieldName": "Customer Posting Group", "MappedName": "Customer_Posting_Group", "Validate": true, "CreateRelatedStub": false }
  ],
  "ValidateOnInsert": true,
  "ValidateOnModify": true
}
SQL PreCommand Result=-1
Requesting OAuth token ...
Primary result length: 48211, web service call duration: 00:00:01.8420011
Index #0
Message: String or binary data would be truncated.
LineNumber: 1
Source: Core .Net SqlClient Data Provider
Procedure:
Parameter No_0 = C00010 (NVarChar Size 6)
Parameter Name1 = Sample Customer Name That Is Longer Than The Column (NVarChar Size 52)
Parameter Customer_Posting_Group2 = DOMESTIC (NVarChar Size 8)
Sql table [Customer], 999 inserted, 0 updated

How to Read the Output

Use the Mapping Array to Verify Field-to-Column Assignment

The Mapping array in the request shows exactly which Business Central field numbers and names are being mapped to which SQL column names. This is where field-name and bracket problems become visible: if a MappedName contains characters that are illegal or unquoted in SQL, or does not match the column in the target table, you will see it here before looking anywhere else. SQL syntax errors such as Incorrect syntax near '=' usually trace back to an entry in this array.

Use the Parameter Sizes to Find Truncation

The Size printed for each parameter is the actual character length of the value being sent. Compare each size against the defined width of the matching column in the SQL target table. The parameter whose size exceeds the column width is the one causing String or binary data would be truncated. In the sample above, Name1 has size 52; if the Name column is nvarchar(50), that row cannot be written.

Use the PreCommand Line to Confirm Session Options

If you rely on --sqlprecommand to set a session option or clear a table, look for the SQL PreCommand Result line. If it is missing or reports an error, the pre-command did not take effect and any conclusion about its influence on the run is premature.

Use the Content Line to Rule Out Source Data

On a PUTDATA failure, check the Content: line. If the field named in the error is present with a value in that payload, the source data and the mapping are not the problem; the error originates in the target table's own triggers. See Import Errors.

Use the Summary Line to Judge the Outcome

The closing Sql table ... inserted, ... updated line tells you whether any rows were written despite the errors. Rows that trigger a SQL error are not written; other rows in the same run may still be inserted or updated.

Verbose Mode in Other Contexts

Context How to enable
Command line Add -v to the command
Service Task Enable Verbose Output logging in the Defaults section of the Service Task Card
Windows service (agent) Set "verbose": "true" in bccl_service.json and restart the service; output goes to the Windows Event Viewer
Registration check BCCL --check --verbose

Tips and Best Practices

  • Add -v first, before changing anything else. The output usually removes the need for guesswork.
  • Keep the mapping file and the verbose output together when you send them to support; the Mapping array and the parameter list are read side by side.
  • If a SQL error does not show the generated statement, check your client build; from 3.23.0.374 the statement is included. See Client Versions and Updates.
  • Disable verbose mode for routine production runs. It produces large output and slows the console.
  • Replace real tenant IDs, secrets, connection strings and customer data with placeholders before sharing output.