Getting Support

When you encounter an issue that you cannot resolve on your own, BCCL provides several diagnostic tools and support channels to help you get back on track. This page explains how to gather the information you need and where to go for help.

Diagnostic Tools

Verbose Mode

The most important diagnostic tool in BCCL is verbose mode. Adding the -v flag to any command causes BCCL to output detailed information about every step of the operation:

BCCL.EXE -v -t getdata -s table=18 -f json -o customers.json

Verbose output includes:

Connection details: The web service URL being contacted and the authentication method in use.
Authentication flow: Token requests, credential sources, and authentication results.
Request details: Each HTTP request sent to Business Central, including URL, headers, and body size.
Response details: HTTP status codes, response sizes, and timing information.
Paging information: How many pages were requested and how many records were returned per page.
Data processing: Format conversion steps, mapping application, and validation results.
Error details: Full error messages and stack traces when something goes wrong.

Always capture verbose output when reporting an issue. It dramatically speeds up diagnosis. For a walkthrough of the verbose output and how to read it, see Diagnosing with Verbose Mode.

Version Information

Running BCCL without any arguments displays the current version number:

BCCL.EXE

The output shows the BCCL version, which is essential information when reporting issues. Different versions may have different behavior or known issues.

Released clients are published on the hougaard.com BCCL download page at https://www.hougaard.com/on-premises/BCCL, and beta or pre-release clients in the on-premises beta area at https://www.hougaard.com/on-premises/BCCL/beta/. Support may ask you to test with a beta or a specific build. Only the BCCL.EXE (or BCCL) executable needs to be replaced; no reinstall is required because the client is a single self-contained file, and the 3.x client remains compatible with a 2.x BC extension. The client executable and the BC app do not have to be on identical version numbers. See Client Versions and Updates.

Registration Check

To verify your license status:

BCCL.EXE --check

This shows whether BCCL is registered, the license type, expiration date, and the associated tenant ID.

Log Sources

BCCL writes diagnostic information to different locations depending on how it is running.

Console Output (CLI Mode)

When you run BCCL from the command line, all output goes to the console (standard output and standard error). To capture this output to a file for later review:

Windows Command Prompt:

BCCL.EXE -v -t getdata -s table=18 -o data.json > bccl_log.txt 2>&1

PowerShell:

& BCCL.EXE -v -t getdata -s table=18 -o data.json 2>&1 | Out-File bccl_log.txt

Bash:

./BCCL -v -t getdata -s table=18 -o data.json > bccl_log.txt 2>&1

Windows Event Viewer (Service Mode)

When BCCL runs as a Windows service, it logs events to the Windows Event Viewer. To view these logs:

Open Event Viewer (search for it in the Windows Start menu or run eventvwr.msc).
Navigate to Windows Logs > Application.
Filter by source: BCCL.

Events are categorized as:

Level	Meaning
Information	Normal operational messages such as task start and completion.
Warning	Non-fatal issues such as token refresh or retry attempts.
Error	Failures including authentication errors, connection failures, and data processing errors.

Service Task Logs in Business Central

When BCCL operations are triggered as Service Tasks from within BC, the task execution log is stored in Business Central itself. You can view these logs on the BCCL page:

Task Status: Shows whether the task succeeded, failed, or is still running.
Task Log: Contains detailed output from the BCCL execution, equivalent to console output in CLI mode.
Error Messages: Highlighted separately for quick identification.

Online Documentation

The official BCCL documentation is maintained at:

https://www.hougaard.com/bccl-user-guide/

This site contains:

Getting started guides.
Detailed explanations of every feature and parameter.
Sample scripts and configuration examples.
Video tutorials for common scenarios.
Frequently asked questions.

Check the online documentation first when you encounter an unfamiliar feature or behavior. It is regularly updated to reflect the latest BCCL version.

Community Support

BCCL has a community of users who share knowledge and help each other with integration challenges. Community support channels include:

Forum discussions on the hougaard.com website.
Blog posts covering common use cases and advanced techniques.
Video walkthroughs demonstrating step-by-step solutions.

Community support is a good resource for general questions, best-practice advice, and creative solutions to integration challenges.

Contacting Hougaard.com

For issues that require direct assistance from the BCCL development team, contact hougaard.com:

Website: https://www.hougaard.com
Support requests: Submit through the hougaard.com contact page or e-mail support@hougaard.com.
License inquiries: Purchase, renewal, and license management, including resetting a license registered on the wrong tenant, moving a license to another tenant, and temporary two-tenant periods during a migration. See License and Registration Issues for what to include in such requests.
Client builds: If the build you need is not yet on the download page, ask support and it will be uploaded. When support identifies a client-side defect, a newer or beta build may be offered; replacing the executable is sufficient to pick it up.

When contacting support, include the information listed in the next section to ensure the fastest possible resolution.

Before raising a ticket about a licence-related error message, verify that the error actually comes from BCCL. Errors worded A valid license not found for ... are raised by third-party apps, not by BCCL. Use Share Details on the error and check the ... by <Publisher> suffix on the AL call stack lines. See Identifying Which App Raised an Error.

Information to Include When Reporting Issues

When you report an issue, providing complete information helps the support team diagnose the problem quickly. Include all of the following:

BCCL Version

Run BCCL.EXE without arguments and include the version number shown.

Business Central Version

Include the BC version and build number. You can find this in BC under Help > About or in the BC Admin Center.

Error Message

Copy the exact error message text. Do not paraphrase -- the precise wording often points to a specific cause.

Verbose Output

Run the failing command with the -v flag and include the complete output. If the output is very long, save it to a file and attach it.

Command Being Executed

Include the full BCCL command line you are running (with sensitive values like passwords redacted):

BCCL.EXE -t getdata -s table=18 -s "view=WHERE(Status=CONST(Open))" -f csv -o data.csv -v

Environment Details

Operating system: Windows, Linux, or macOS, with version.
Execution context: Command line, scheduled task, Windows service, or CI/CD pipeline.
Network: On-premises BC or BC cloud (SaaS). Any proxy or firewall between BCCL and BC.
Authentication method: Basic, OAuth, or S2S.

Steps to Reproduce

Describe the sequence of actions that leads to the problem. If the issue is intermittent, note how frequently it occurs and any patterns you have observed.

Mapping File (if applicable)

If the issue involves data formatting or field mapping, include the mapping.json file.

Self-Service Troubleshooting Checklist

Before contacting support, work through this checklist:

Check the documentation. The answer may already be documented.
Enable verbose mode (-v) and review the output carefully.
Verify connectivity. Can you reach the BC web service URL from a browser on the same machine?
Check credentials. Try --forget followed by --remember to reset stored credentials.
Simplify the command. Remove optional parameters until you find the one causing the issue.
Test with a small dataset. Use a filter or small page size to isolate data-related issues.
Check BC permissions. Verify the user has access to the table and fields in question.
Review recent changes. Did anything change in BC, the network, or the BCCL configuration since it last worked?
Try a different format. If CSV fails, try JSON. This helps isolate format-specific issues.
Update BCCL. Ensure you are running the latest version. Bugs in older versions may already be fixed. Released clients come from https://www.hougaard.com/on-premises/BCCL, beta clients from https://www.hougaard.com/on-premises/BCCL/beta/. Because BCCL is a downloaded executable that you unpack locally, it does not update itself; unexpected or malformed output is commonly caused by running an older copy.

Known Limitations

Being aware of these known limitations can save you troubleshooting time:

Trial mode limits operations to 100 records upload and 50,000 bytes download. Register BCCL to remove these limits.
Binary fields (images, attachments) are excluded by default due to their size. Use -b to include them.
Legacy Excel format (.xls) is not supported. Use .xlsx.
Non-UTF-8 encodings are not supported for CSV files.
Excel range syntax uses two dots (A1..H100), not a colon (A1:H100).
BCCL 2.x clients can fail with an Int32 overflow (System.OverflowException: Value was either too large or too small for an Int32) when exporting tables containing BigInteger/Int64 values outside the Int32 range, such as fields added by the Shopify Connector. The BCCL 3.0 client resolves this. See the overflow entry in Common Issues.
Obsoleted fields cannot be read. If a mapping refers to a field Microsoft has obsoleted, the task fails and the field must be removed from the mapping; there is no option to skip obsoleted fields.
Platform-restricted tables (system or virtual tables the BC runtime will not open through RecordRef on the Cloud target) cannot be mapped or read by BCCL. There is no workaround in BCCL.
One agent runs one task at a time. Tasks queued for the same agent run sequentially; add agents to run in parallel.
Token renewal. BCCL renews an S2S token during a run at about 80% of its reported lifetime; OAuth tokens are never renewed. Tenants that issue very short-lived tokens should use the BCCL3 beta client. See Running Long or Unattended Transfers Reliably.