Troubleshooting

For output that works interactively but fails in a service or web application, check the runtime account and file access.

PDF Output

Unicode Characters Cannot Be Printed

For error 0x697C (27004), check the text, font and PDF settings:

Verify that the input contains the intended characters. For imported text files, check the input encoding.
Make the required font available to the account running TFORMer and check that it contains the affected characters. See font linking and substitution; on Linux, also check font availability.
Check font embedding in the configuration file selected by your application. For TrueType subset embedding, set embed-fonts="1", embed-subset-fonts="1" and embed-type3-fonts="0" on its existing PDF element.

Embedding does not add missing characters to a font. Generate the PDF again and check the affected text.

ZPL Output

Labels Have the Wrong Size or Orientation

For direct ZPL output, check the layout and SDK output settings rather than the Windows printer driver's page settings. Also check the defaults in your TFORMer.xml configuration.

Label size
Compare the layout's page size and selected media with the loaded labels. If needed, override the media setting. For example, media="Custom.320mmx30mm" selects a size of 320 × 30 mm; use the dimensions required for your labels.
Orientation and rotation
Check orientation (for example, orientation=landscape) and any additional rotation (rotation=90 adds 90° counter-clockwise). Choose values that suit your layout; these examples are not a required combination. See Page Setup for details and supported values.
Resolution
Match output resolution to the printer's DPI, for example resolution=203 for a 203-DPI printer.

Set options through the entry point for your interface, then check a test label on the target printer.

Printer Does Not Rewind Labels

Check printer support
Rewind mode requires a supported printer model with the required equipment and media setup. See Zebra's ^MM command reference for the available print modes.
Set the rewind command
For a compatible printer, select ZPL output and set header=^XA^MMR^XZ through the entry point for your interface before generating output. This places the rewind command at the beginning of the ZPL output. It replaces the configured header; include any other required header commands in the same value.
Check the result
Print a test label on the target printer and check whether it is rewound as intended.

For commands at the end of a job, see footer.

Windows

Native Library Cannot Be Loaded

If .NET reports DllNotFoundException for a TFORMer DLL, the named file or one of its dependencies may be unavailable. Check:

Process architecture: Use x86 libraries for a 32-bit process and x64 libraries for a 64-bit process, regardless of the Windows architecture.
Deployment: Provide the matching native files from the same SDK release and the required Microsoft Visual C++ runtime. See Windows deployment requirements.
Published application: For NuGet-based applications, check the deployed Publish output, not just the SDK installation on your development machine. See .NET deployment.

Paper or Label Size Differs from Designer Output

Designer and SDK output can use different printer settings. Compare:

The selected printer queue and driver.
Paper size and orientation in the Designer print dialog and the printer settings available to the account running your application.
The layout's page settings and any output options set by your application.

Use the same settings when comparing results. See Page Setup for explicit media and orientation options. For services, also check the runtime account.

Barcode Bars Are Enlarged or Distorted

If bars are enlarged or distorted when printing through a Windows printer driver, try the option string tbarcode-drawing-mode=quality. Set it through the entry point for your interface, then check the printed barcode on the target printer.

The drawing-mode option applies to Windows printer output, not direct ZPL or image export. For ZPL output, check that output resolution matches the printer's DPI.

Slow Printing to a Remote Windows Printer

Delays with a UNC printer name such as \\server\printer can depend on the network, print server and printer driver.

If the queue is not installed on the SDK machine, ask your administrator to install or connect it with the appropriate driver. Repeat the same print job under the same runtime account and compare the time taken. A connected queue does not guarantee faster printing.

If the delay persists, send support the SDK version, printer and driver details, and the operation where the delay occurs.

Linux

Collect Diagnostic Information

If the TFORMer SDK installation or runtime does not work as expected, collect diagnostic information with the installed support script:

$ /usr/local/share/TFORMer9/support.sh > tformer-support.log

The script reports the operating system, TFORMer version, shared-library dependencies, available character conversions, configuration, and relevant environment values.

Send the generated log to TEC-IT support at support@tec-it.com together with a detailed error description.

Missing Text

If output contains images, lines, and other graphical elements but no text, check the character conversions available to the account running TFORMer. The Linux runtime uses the system iconv implementation; the support script lists the available conversions.

Incorrect Special Characters

Special characters can be incorrect when a text input created on Windows is interpreted with the wrong encoding on Linux. Prefer UTF-8 input, or configure the text input encoding for the selected API or tfprint workflow.

For example, convert a Windows-1252 text file to UTF-8 with:

$ iconv -f Windows-1252 -t UTF-8 input.csv > output.csv

Missing or Substituted Fonts

TFORMer uses fontconfig on Linux to match the fonts requested by a layout with fonts available to the runtime account. If the requested font is unavailable, fontconfig may select a substitute and the output can look different.

Use fc-list to list fonts visible to the current account.

Installing TrueType fonts

Install the required fonts with the operating system or distribution font-management procedure at a scope visible to the account that runs TFORMer. For a service, verify font visibility while using the service account.

If the supported distribution requires a font-cache refresh, follow its fontconfig guidance using the prescribed identity and scope.

See the fc-list and fc-cache man pages for the options supported by the installed fontconfig version.

Native Library Not Found

The Linux package installs libTFORMer9.so and its matching versioned targets in:

/usr/local/lib/

For compilation, add this directory to the linker search options when required, for example -L/usr/local/lib. At runtime, make the directory available through the platform dynamic-library loader configuration.

Header Files Not Found

The Linux package installs TFormer.h and the supporting headers in:

/usr/local/include/TFORMer9/

The packaged C sample includes the headers as TFORMer9/TFormer.h and uses -I/usr/local/include.