1. CPQ
  2. Document Automation
  3. Output Builders

Troubleshooting Output Builders

Article last updated:


When your output file is not building correctly, try these suggestions to resolve the problem.

If using a local builder, check the local builder logs

Most builds (word, Excel, Zip, PDF, and the like) are done quickly and easily using our cloud builder.  However, CAD outputs are done on your local builder which you maintain.  If you are troubleshooting a problem from a local builder, remember to check the local builder logs.  When a CAD builder launches to process a template into an output document, it makes entries in the log file on that local machine.  This is often the best place to start.

  1. Gain access to the desktop of the output builder that processed the troublesome configurator.
    (If your company has multiple builders assigned to a queue, you may find it hard to determine which builder processed the document.  Try temporarily disabling all but one builder from the queue, so you know which machine is performing the build. To disable a builder, simply exit the builder program on that workstation.  Remember to re-start it later when your troubleshooting is done.)

  2. In the tooltray of that desktop, click the icon for the epicor output builder.  The Builder window appears.  Click the "logs" tab to see the local logs.
  3. Log entries of interest are the orange checkmarks (warnings) and red exclamation marks (errors).

 

Check the server logs and jobs

Other useful information may be available server-side.

  1. Log in to the appropriate Epicor CPQ environment: dev, test, or production.
  2. Click the gear icon to see the administrative menu, and choose
    1. Infrastructure > Logs to see log files.
    2. Infrastructure > Jobs to see details of server-based jobs.

 

Builder Error Messages and Possible Reasons

Use this list as a source of possible problems. This list is not exhaustive, and your local builder's platform or version may behave differently. 

Message Possible Reason

"The parameter is incorrect"

E_INVALIDARG

An attempt to upgrade the template is failing.

The CAD software is a more recent version than the template it is opening.  It is asking if you want to save the template in this new version, but the dialog window prevents the automated build from completing.

To confirm this reason:

Try opening the same template manually, yourself, on that workstation.  Then close the template.  If the CAD software shows any dialog boxes to you between opening and closing the template, this may be the problem.

To solve this problem:

  1. Stop the output builder on that workstation.
  2. Open the same template yourself, manually, on that workstation.  Resolve any issues, such as saving the template in the latest version so the CAD software doesn't try to upgrade it any more. Ensure you can open and close the template without any prompts. 
  3. Save the updated template to the cloud. Upload it into Resources > Templates.  All output builders will download this update automatically when they need it.
  4. Restart the output builder on that workstation by launching it again. (Search the workstation's start menu for "output builder" to find that application and launch it.)
  5. If this solves the problem, review and re-save your other templates as necessary.

"The parameter is incorrect"

"Non-unique project filenames"

E_INVALIDARG

The CAD software found two or more files with the same name.

The CAD software is trying to open a template, component, or other file, or trying to save an output document.  However, more than one file exists with that name.  It is asking how to proceed in a dialog box, but that prompt prevents the automated build from completing.

To confirm this reason:

  1. Try opening the same template manually, yourself, on that workstation.  Then close the template.  If the CAD software shows any dialog boxes to you between opening and closing the template, this may be the problem.
  2. Scan the files in the output builder's "Template" folder and the "Results" folder. If two files in those two folders have the same name, some CAD applications may warn with a dialog box, which prevents the output builder from finishing.  (You can easily find duplicates by creating a new third folder, then copy/pasting the files from the other two folders into this temporary folder.  The OS will warn you when it finds a duplicate filename during the second copy/paste.)

To solve this problem:

  1. Save the updated template to the cloud. Upload it into Resources > Templates.  All output builders will download this update automatically when they need it.
  2. Restart the output builder on that workstation by launching it again. (Search the workstation's start menu for "output builder" to find that application and launch it.)
  3. Ensure no filename appears in both the "Template" folder and the "Results" folder. 
  4. If the duplicate file name is coming from the output file which is being created as part of the build, then change the Snap rules which name that file.  For example, append a unique string to the filename, such as an iterator or a string showing a portion of the current date (use the "format" and "now" Snap blocks).
"Failed to create folder"

"syntax is incorrect"

The filename you're using contains special characters.

Check the Snap rule which is naming your output file.  If it is using data from fields within the configurator, that data may contain characters which cannot be used in a Windows file system.  Characters like " or \ are not allowed.  For example, the following Snap code in a build rule could cause this error, if the quote name is "Mary's v1\v2 request"

To confirm this reason:

Add a Write log...info Snap rule before the Set output rule, to show the name being written.

To solve this problem:

  1. Create a function in Snap that replaces any special characters with a legal character, such as _ or .  Use that function when writing the targetFilename. The "replace" Snap block would be useful here.

 

Resetting the output builder

If the output builder launches and then immediately closes, or the behavior seems otherwise strange, you can reset the output builder by deleting these cache folders and their contents, if they exist:

%homepath%\AppData\Local\Epicor
%homepath%\AppData\Roaming\Epicor
%homepath%\AppData\Roaming\Epicor3

If you have had an older version of the output builder installed on this computer, you may also see these folders (which can also be deleted):

%homepath%\AppData\Local\KBMax
%homepath%\AppData\Roaming\KBMax
%homepath%\AppData\Roaming\KBMax3

Was this article helpful?