Dispatcher: Troubleshooting

Bisect by state first

The request state names the owning component. Do not read logs before reading the state. See Request lifecycle for the full table; the short version:

Stuck at	Suspect
INITIAL	Dispatcher Client not running, or not polling
PREPARING	TaskPrep, dataset type, named references
SCHEDULED	No Module advertises the service, or all are at MaximumTasks
TRANSLATING	The translator script, or the progress watchdog
LOADING	DatabaseOperation, destination type / named ref / relation

Then open the right log

Dispatcher writes one log per component per task under Dispatcher/Logs/Dispatcher/task/<taskId>/:

File	Component
<taskId>_dc.log	Dispatcher Client
<taskId>_s.log	Scheduler
<taskId>_m.log	Module

The triplet maps one-to-one onto the state machine, so the state you are stuck in names the file to open. There are also per-component rolling logs (Scheduler.log, Module_*.log, DispatcherClient_<ip>_<port>.log) alongside.

The Command string: line in the module log is the most valuable line in Dispatcher. It is the fully-resolved command with every option substituted. Copy it, run it by hand on the Module host, and you have isolated your translator from the entire framework in one step.

The failure modes worth knowing in advance

⚠⚠⚠ "Translation request missing primary object" is an ACL failure in disguise

The most misleading error in Dispatcher. Observed live:

INFO  - Begin Extract of Request <taskId>
ERROR - Translation request missing primary object.
    java.lang.Exception: Translation request missing primary object.
        at com.teamcenter.ets.request.TranslationRequest.refreshPriAndSecObjs(TranslationRequest.java:1244)
        at com.teamcenter.ets.extract.Extractor.processRequest(Extractor.java:388)

The request is not missing a primary object. refreshPriAndSecObjs() re-resolves the primary and secondary object references inside the Dispatcher Client's own Teamcenter session — the session belonging to Service.Tc.User. If that account cannot see the object, the reference resolves to null and is reported as "missing".

So this message means: the DC Proxy User cannot read the data you pointed it at. It says nothing about the request itself. Confirm by reading the same object as Service.Tc.User in an independent session; if that fails too, the problem is access, not the request.

On project-secured data this is the default outcome, because the DC Proxy User is typically a dba-group service account with no project context. Two things are required, and the second is easy to forget:

1. The DC Proxy User must be a member of the project and have it set as its default project, so its session carries that project context.
2. The Dispatcher Client must be restarted. It holds a long-lived session (Service.Tc.ReLoginInterval defaults to 1440 minutes), so it will not pick up new access for 24 hours otherwise. A request fired after the grant but before the restart fails identically and looks like the grant did not work.

Corollary for multi-program sites: a Teamcenter session has exactly one current project, so one DC Proxy User serves exactly one program. That is a structural constraint, not a policy choice.

preferences_manager that does nothing and says nothing

Two failure modes that both look like success, and cost real time:

It needs the Teamcenter environment in the invoking process. Having TC_ROOT and TC_DATA set as variables is not enough — the executable needs Teamcenter's library directories on PATH, which is what tc_profilevars does. Without it the process fails to load its DLLs and prints nothing at all:

EXIT CODE = -1073741515      # 0xC0000135 STATUS_DLL_NOT_FOUND

Wrap it so the environment is loaded in the same process:

@echo off
call "%TC_DATA%\tc_profilevars.bat"
"%TC_ROOT%\bin\preferences_manager.exe" -u=<user> -p=%1 -g=dba -mode=import -scope=SITE -action=override -context=Teamcenter -file=<file>
echo EXITCODE=%ERRORLEVEL%

A successful run is chatty; a failed one is silent. Success prints The import operation has succeeded. and a report-file path. Any failure to launch prints nothing and returns to the prompt looking identical to success.

Always capture $LASTEXITCODE, and always verify by reading the preferences back as a different user after refreshPreferences. Never chain the import with Restart-Service using ; — a failed import still restarts the service, and the whole sequence looks like it worked.

Fully configured, never runs, nothing logged

Observed live: a translator registered in translator.xml with isactive="true", a launch script in place, Prepare/Load bound in Service.properties, and all six extract/load preferences set — which had never run once in 2,715 tasks over four months, because the ETS.DATASETTYPES.<PROVIDER>.<SERVICE> menu preference was never created.

Without it the service never appears in the Translation Selection dialog, so no request is ever created, so there is nothing to log and nothing to fail. It is indistinguishable from a working translator by inspecting the Module host alone.

Check both preference families before anything else. They are independent. See Live configuration evidence for a one-call probe.

Stderr output that is not actually a failure

A live successful task log contains Standard Error : Processing queue and still ends Completed successfully!. Writing to stderr does not fail a task. Only a <TransErrorStrings> match or a non-zero exit does. Do not spend a day silencing a chatty translator that is working.

isactive="false"

All 78 OOTB services ship inactive except tozipfile. A perfectly configured service that never picks up work is this, far more often than anything else. Check Module/conf/translator.xml first, every time.

A translator that exits 0 and still fails

<TransErrorStrings> scanning. Dispatcher greps stdout and stderr for declared substrings and fails the task on a match regardless of exit code. Conversely, a translator that prints a benign line matching a site-wide <ErrorStrings> pattern fails for no visible reason. The fix is <ErrorExclStrings> or the per-translator addExclErrorString() / addExclInputString(), not suppressing your own output.

Failure at roughly 50 minutes

MaximumProgress=100 × MonitorInterval=0.5 = a 50-minute default ceiling on one translation. Large models hit this. Raise MaximumProgress.

Filenames silently changed

BadChars in DispatcherClient.config replaces a long list of characters (including -, ., space and parentheses) with underscores before translation. If your script does exact filename matching, it is matching the sanitized name. Override per service with <Provider>.<Service>.BadChars.

Related: the shipped proetojt TaskPrep sanitizes deliberately before translation so that source-to-result mapping still works afterward, and appends an index (a_b0.prt, a_b1.prt) because sanitizing can collide two distinct names into one.

"No translation result found"

Specific and useful. It means the Dispatcher Client side worked and nothing came back, which almost always means the Module has no such translator configured. The ppttopdf sample readme calls this out by name as the expected error when the Module half has not been done.

Staging directory mismatch under RMI

With RMI file transfer, Staging.Dir must be set on both the Client and the Module and must resolve to the same physical location. HTTP transfer tolerates an empty value; RMI does not.

Your new jar throws Class not found under the Windows service

The highest-value gotcha for anyone adding custom classes. Siemens KB PL8828085: a customer added Prepare/Load classes in a jar, registered them in Service.properties, and extended CLASSPATH in DispatcherClient\bin\setDispatcherClientEnv.bat. The DispatcherClient still threw Class not found.

Cause: when the Windows service is created with runDispatcherClientWinService.bat -i, the classpath is written into the registry under HKLM\SYSTEM\ControlSet001\Services\Teamcenter DispatcherClient <version>\Parameters. Editing the batch file afterwards changes nothing, because the service never reads it again.

Fix: reinstall the service.

runDispatcherClientWinService.bat -r
runDispatcherClientWinService.bat -i

Reproduced on TC V2312.0004. Expect to hit this the first time you deploy a custom TaskPrep.

The Translation menu appears when Dispatcher is not installed

Siemens KB PL8045532: the Translation menu shows up in My Teamcenter even when the Dispatcher client for rich client feature was never selected at install. The documented behavior is that it should only appear when the feature is installed. It does not.

So menu presence proves nothing. Neither does DISPATCHER_CLIENT_INSTALLED=true. Confirm the Scheduler and Module processes independently before concluding Dispatcher is deployed.

Result file exists but the loader says it is missing

If the result is a text file, see KB PL8123093: text named references are defined by * rather than *.txt, so the loader looks for myfile when the translator wrote myfile.txt, and reports the result missing immediately. Fixed in TC 12.2 (PR 9448791). Adding .txt to OutputExtensions in translator.xml does not work around it.

Staging directory on a network share

KB PL8674963: with a NetApp share mapped as a Windows network drive as the staging directory, prepare.exe could not read the input file and reported the Result directory as not writable, silently writing the PDF to TEMP instead. Reproducible from the command line, with no custom code involved. If your staging directory is a mapped drive rather than a UNC path or local disk, test the translator standalone against that exact path before blaming Dispatcher.

Windows service will not start

The guide has a specific entry: "Unable to run Dispatcher components as Windows service due to missing DLL file." Also check that the system and environment variables needed to run the dispatcher client as a Windows service were set as part of post-installation.

Terminal state from too many open files

A documented failure: "Dispatcher requests go to terminal state due to large number of files open." Relevant on assembly translations and on Unix Modules with default ulimits.

Unicode / Cyrillic

Both an admin-guide section ("Support for Unicode and Cyrillic character encoding") and a post-installation task ("Update Dispatcher components to work with UTF-8 configuration"). If your data is not ASCII, do the UTF-8 step during install rather than debugging it later.

NXToPvDirect hangs

Has its own troubleshooting section. Direct translators behave differently from the standard extract/translate/load flow: they write into Teamcenter themselves and use PostProcessor.xml file mapping rather than Load classes. Do not debug them with the standard model.

Multiple named references after translation

Also documented: "Multiple named references added after the translation process." Usually destination named-reference configuration interacting with the replace-existing flag.

⚠⚠ A translator that silently lost a feature: version skew on the Module host

Observed live. A translator that had been running end to end for days was producing its main artifact correctly but silently skipping an entire stage, and reporting success while doing it.

The translator's entry point had been redeployed several times during bring-up. Nothing it calls ever had. The Module host was running a months-old copy of the supporting scripts:

file	Module host	source repo
entry point	current	current
transform	3,887	7,772
the audit step it invokes	absent	12,860

The old transform had no support for the --emit-exchange flag at all. It accepted the flag, ignored it, and exited 0 — so the downstream stage found no input file, skipped itself, and the request still reported success.

Three things generalise:

1. Redeploy the transitive closure, not the entry point. A one-level import grep is not enough. Walk the imports until the set stops growing, then hash every file on both sides and diff the manifest. Deploying six of eight files here produced ERR_MODULE_NOT_FOUND on a helper two levels down.
2. Upgrade the minimum. Version skew caused the fault, but the fix is not "sync everything." Two older modules were deliberately left in place because they still exported the API the new code imports, and replacing them would have put the one proven, verified output at risk to solve a problem it was not causing.
3. Unknown arguments must be rejected, not ignored. This is the same defect class as import_file accepting a misspelled -itemRevVid, printing *** Importing File ***, creating nothing, and exiting 0. If your translator parses its own flags, make an unrecognised one a non-zero exit.

Preventing the silent part is your job, not Dispatcher's. Dispatcher reports the process exit code. If a stage inside your translator is deliberately non-fatal — and a reporting or audit stage usually should be, since its failure must not discard the artifact that was successfully produced — then it will fail invisibly unless you make it speak:

• Capture the stage's stderr, not just its exit code, into your status JSON.
• Log an explicit skipped entry when a stage is bypassed for a missing input, naming the file. A stage that vanishes from the stage list is far harder to notice than one that reports why it stood down.

A request that returns ok with a stage quietly missing is the worst available outcome: the gate is gone and nothing anywhere says so.

⚠⚠⚠ The request succeeded and the artifact is wrong

Every failure mode above announces itself. This one does not, and none of the bisect-by-state advice on this page will find it, because there is no stuck state and no error to open a log against.

Observed live. Two supporting modules on the Module host were updated to close a version skew. The request completed, the dataset was created and attached, the translator's own reconciliation stage passed. The artifact had lost a third of the model: a deduplication step merged components on their name, and the source genuinely contained three Thrusters, three Heaters and three of several other things. Two of every three were destroyed silently.

Symptoms, such as they are:

• The request reaches COMPLETE.
• The output file is noticeably smaller than the last known-good run. On this occasion 1,094,386 bytes became 797,101, and that was the only visible signal.
• Any self-reported quality metric goes down rather than failing, because a smaller model and a broken one look identical from inside the translator.

What to do about it:

1. Keep the artifact size per run. It costs nothing, and it was the only thing that flagged this. A step change in size on an unchanged model is the tell.
2. Reconcile against the extract, not against your own intermediate. See Anatomy of a working translator for the check and the four rules it produced. A translator comparing its output to its own intermediate cannot detect anything it dropped before writing both.
3. Never conclude "no error" means "no problem" on this stack. import_file accepts a misspelled option, prints *** Importing File ***, creates nothing and exits 0. A transform accepted a flag it did not support, ignored it and exited 0. Now a translator discarded 43 components and exited 0. Three separate silent-success defects on one deployment.

A note on change control. All three arrived through partial or unvalidated redeployment of a translator's supporting files. Treat a translator's dependencies as part of the translator: version them together, deploy the whole transitive closure, and re-validate the output against the source afterwards — not just that the request still completes.

Diagnostic tooling

Task	How
Is it even running?	-ping, supported by all three Dispatcher components (Scheduler, Module, DispatcherClient). This is the first command to run, and the fastest way to settle "is Dispatcher deployed here"
List and manage request objects from the CLI	dispatcher_util (documented in the Utilities Reference, present from TC 10.1 through at least 13.2). Lists requests and manages request objects without the rich client
Set debug levels	Admin guide 10-3; log4j2 per component in conf/log4j2.xml
Query request objects	Admin guide 10-4
View request logs	Attached to the request. Controlled by Translator.<p>.<s>.Log and .LogsForComplete
View service runtime status	start_sco_dispatcher utility; also a JMX surface (com.teamcenter.tstk.util.jmx.module, ...jmx.scheduler)
Admin console	Refresh, resubmit, delete, filter requests; view properties and attached logs

Log files land under LogVolumeLocation (default ../logs) per component. LogManager.DeleteTime is unset by default, meaning logs are never auto-deleted. Set it (in minutes) on a long-running site.

By default no logs are attached to successful requests (LogsForComplete=false), and the client looks for <provider>_<translator>.log in the result directory when no filenames are specified.

Two claims to be careful with

"Dispatcher is installed" usually means someone set DISPATCHER_CLIENT_INSTALLED=true. That preference makes the Translate menu appear. It says nothing about whether a Scheduler or Module exists. Confirm the processes independently.

"The translator is configured" usually means a block exists in translator.xml. Confirm isactive="true" and confirm the script runs standalone.

Escalation path

The admin guide's own checklist order: isolate the translation problem, raise debug levels, query the request objects, read the attached logs. Run the translator standalone at the first sign of trouble. It removes four subsystems from the problem in one step.