Troubleshooting Output Builders

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

Find Errors in the Local Builder logs

Most builds (word, Excel, Zip, PDF, and the like) can be done 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).
   
   

Find Errors in 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, Reasons, and Solutions

After reviewing the logs, 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 Reasons & Solutions
"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: Stop the output builder on that workstation. 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.  Save the updated template to the cloud. Upload it into Resources > Templates.  All output builders will download this update automatically when they need it. 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.) 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: 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. 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: Save the updated template to the cloud. Upload it into Resources > Templates.  All output builders will download this update automatically when they need it. 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.) Ensure no filename appears in both the "Template" folder and the "Results" folder.  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: 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.

Isolate the problem: CAD file, or CAD builder?

If your problem continues, try to isolate it.  Specifically, determine if the problem is with the CAD file being built, or with the builder machine responsible for creating it.

1. Did your problems start after updating a CAD build's Snap rules within a configurator, or editing the CAD template used by that configurator?
   • Isolate the problem to that one CAD output: try building another, separate CAD document from another configurator. If you don't have another configurator making a CAD output, simply create a new cube configurator with a simple cube CAD output file. Test the build on the same output builder. If your test cube build works, but the problem continues on your recently-modified build, then investigate those changes made. You can also roll-back your changes to that configurator.
2. Did your problems start after making changes to the output builder computer, such as a software update or IP address?
   • Isolate the problem to that one builder: try building the same troublesome CAD document on another builder machine. If you don't have another builder machine, simply set up your personal CAD workstation as an output builder temporarily. If that same troublesome CAD document works on that other builder, but the problem continues on your original builder, then investigate any changes made to that builder. Or reset the builder by following the steps below.

Resetting a Local Output Builder

If the output builder launches and then immediately closes, or the behavior seems otherwise strange, follow these steps.

1. Shut down the output builder machine.

   • Gain access to the computer's desktop.

   • Find the output builder tooltray icon, and right-click it. Open the application, so the builder window runs.

   • To log out of the output builder, click the "logout" button next to the minimize button at the top right of the output builder.

   • In the pop-up menu that appears, select Exit.

   • The output builder program will stop, and the icon will disappear from the tooltray.

2. Shut down the CAD program.

   • See your CAD program manual for the correct procedure.

3. (Optionally, at this stage you can perform other housekeeping tasks such as ensuring Windows updates have been applied, or restarting the operating system for good measure.)

4. Launch the CAD program.

   • Follow your vendor's procedure for starting the CAD program. For troubleshooting purposes, ensure that only one instance of the CAD program is running.

5. Launch the output builder.

   • Find the "CPQ Output Builder" application in the Windows start menu and launch it. The icon will re-appear in the tooltray. After restarting the builder, it connects to its assigned queue and will begin processing any work there.

6. Confirm output builder operation.

   • Confirm the current status of the output builder is "watching..." or some other activity.

Re-Installing a Local Output Builder

In some situations, you can try to uninstall and reinstall an output builder.

1. Shut down the output builder machine.

   • Gain access to the computer's desktop.

   • Find the output builder tooltray icon, and right-click it.

   • In the pop-up menu that appears, select Exit.

   • The output builder program will stop, and the icon will disappear from the tooltray.

2. Shut down the CAD program.

   • See your CAD program manual for the correct procedure.

3. Uninstall the builder.

   • Use the system settings > add or remove programs feature of windows to uninstall the Epicor CPQ output builder program.

   • When the unistall completes, ensure the following folders and their contents have been deleted by the uninstaller. If you see these folders after an uninstall, you can safely remove them. They will be rebuilt when you re-install the builder in the next step.

     • %homepath%\AppData\Local\Epicor

     • %homepath%\AppData\Roaming\Epicor

     • %homepath%\AppData\Roaming\Epicor3

     • %homepath%\AppData\Local\KBMax

     • %homepath%\AppData\Roaming\KBMax

     • %homepath%\AppData\Roaming\KBMax3

     • %homepath%\AppData\Local\Caphyon\Advanced Installer

4. Restart the computer.

5. Reinstall the builder from a fresh installer, found in the CPQ admin portal under infrastructure > tools > Download Output Builder.

See Also...

• Setting up a local builder
• Using a local builder