Troubleshooting Workflow Builder
Diagnose common installation, service, and configuration issues for Workflow Builder, and gather the information needed to open a support case.
Installation directory and log files
Default installation directory: C:\Program Files (x86)\BigFix Enterprise\BFWorkFlow\
Log files are located under workflow-data\logs in the installation directory. The BigFix Workflow Service writes two log files:
| Log file | Content |
|---|---|
| wrkflw_cli.log | Main CLI application log. Every invocation of bf-wrkflw.exe from the command line backs up the previous log and creates a new one. |
| wrkflw_svc.log | Log of the BigFix Workflow Service (service name
BigFixWorkFlow). |
Installation and CLI issues
The symptoms below are read from workflow-data\logs\wrkflw_cli.log
after running bf-wrkflw.exe:
| Symptom (log) | Root cause | Resolution |
|---|---|---|
bf-wrkflw.exe --install does not install; the
log shows ERROR … [SETP] DB_HOST is required. |
The configuration file was not passed. | Rerun with -f <file>. |
--install -f <file> fails; the log shows
Resolved runtime .env file path: <file> is not
FOUND! followed by DB_HOST is
required. |
<file> does not point to a valid file. |
Correct the path; ensure the file exists and is accessible. |
--install -f <file> fails; the file
resolves, then DB_HOST is required. |
The file exists but misses mandatory parameters. | Add the mandatory keys (see Manual installation) and rerun. |
A second installation attempt fails; the log shows
ERROR … [SETP] DB_PASSWORD is required. |
DB_PASSWORD is removed from the file after use,
for security. |
Edit the file, add the database password again, and repeat. |
Installation fails during database verification; the log shows
mssql: login error: Cannot open database
"BFEnterprise" requested by the login. |
The database defined in DB_NAME must exist;
Workflow Builder is expected on the BigFix Platform database
(BFEnterprise by default). |
Ensure that the database exists and the connecting user has access to it. |
| Installation fails during database verification with a login error for the user. | Incorrect database password provided. | Provide the correct password. |
BigFix Workflow Service issues
The symptoms below are read from workflow-data\logs\wrkflw_svc.log or seen in the BigFix UI:
| Symptom | Root cause | Resolution |
|---|---|---|
The service log repeats DEPENDENT SERVICES: Checking
for mTLS certificate and mTLS certificate not
available yet … lbLite: secret not found. |
The mTLS setup has not been performed yet; the BigFix Workflow
Service is waiting for the certificate that BFUI.exe
--configure-wfb provides. |
Run the activation (see Stage 4: Activate the application in the BigFix UI). Until then, this waiting loop is expected. |
| Steps do not load in the editor: the Action library shows No results found in the selected categories (see the figure below). | The step-library API of the BigFix Workflow Service is down. | Restart the BigFixWorkFlow service. |
| The BigFix UI sometimes shows only the Home menu; other navigation entries (including Resolve > Workflow Builder) are missing. | One or more API services that supply the navigation data were unavailable when the page rendered. | Hard-refresh the browser (Ctrl+Shift+R); when the APIs respond, all entries appear. |
BigFix UI configuration issues
If the application does not appear or does not respond in the BigFix UI, verify the network connectivity between the BigFix UI and the BigFix Workflow Service host, the mTLS activation, and the wrkflw_svc.log service log. If the Workflow Builder tile remains Not Configured in Administration > Application Configuration, a background configuration process has failed: check the service logs as directed by the toaster message, resolve the error, and run the configuration again.
If the BigFix UI setup fails at the database step with DSN connection test
failed Unsupported SQL Server version, the SQL Server instance for the
BigFix UI database is older than SQL Server 2025 (17.0). Use a SQL Server 2025
instance for the BigFix UI database, and then run the setup again (see Prerequisites).
The symptoms below appear on the console of BFUI.exe
--configure-wfb or in the BigFix UI logs on the BigFix UI server:
| Symptom | Root cause | Resolution |
|---|---|---|
BFUI.exe --configure-wfb fails with
wfb configuration failed: … failed to post to MTLS
resource: Post "https://<acceptor>:<port>/create-csr":
… target machine actively refused it. |
The BigFix Workflow Service is down, or the port is not reachable from the BigFix UI server. | Start the BigFixWorkFlow service on the BigFix
Workflow Service host and rerun the command. |
The BigFix UI logs requesting frontend step library …
tls: failed to verify certificate: x509: certificate signed by
unknown authority. |
mTLS is configured, but the BigFix UI or the BigFix Workflow Service is referring to an old configuration. | Restart the BigFix UI and the BigFix Workflow Service. |
The BigFix UI reports 503 Workflow Builder Service is
not configured and Workflow Builder Setup is
missing. Please Verify Configuration Settings. |
mTLS between the BigFix UI and the BigFix Workflow Service is not configured, or is configured incorrectly. | Fix the mTLS configuration (see Stage 4: Activate the application in the BigFix UI),
and then restart the BigFixWorkFlow service:
sc stop BigFixWorkFlow, then sc start
BigFixWorkFlow. |
Opening a support case
When you open a support case for Workflow Builder, provide the following information (must gather):
- The BigFix Platform version.
- The BigFix UI version.
- A screenshot of the observed issue.
- The steps to reproduce the issue.
- If the issue is related to the workflow definition or to its transpilation into ActionScript: the workflow exported in JSON format. Open the workflow for editing, select JSON editor, and select Download (see Working with the Live JSON editor).