Troubleshooting Guide¶
Start every investigation with the environment check:
uft-migrate doctor
It verifies Windows, Python, pywin32, the UFT installation, the IronPython
runtime, the ALM client, and output-folder write access — and can test a live
ALM login with --alm-url/--username (password via the
UFT_MIGRATE_ALM_PASSWORD environment variable). An offline-package row
marked [ -- ] is normal on an installed copy: that check is for whoever builds
the package, not for you. Its license row names the edition in use: the free
edition, or your installed license.
Installation and environment¶
"pywin32 import failed: No module named 'win32com'"¶
ALM and UFT automation require pywin32. What to do depends on how Phoenix was installed.
Installed with MeritoPhoenixForUFT-<version>-Setup.exe (the recommended
install). pywin32 is already present in the product's own runtime, and the
package build import-tests it before the package is sealed. If doctor still
reports this, that runtime is damaged: run the installer again, as
administrator, over the existing installation — it replaces the installed files
in place. Do not install packages into the product runtime — it carries no
pip.
Installed from source with pip (development only — see
install.md § Installing from source). Install pywin32 into the
same 32-bit Python that runs uft-migrate:
python -m pip install pywin32
If COM errors persist after installation, run the post-install script once from
an elevated prompt: python Scripts\pywin32_postinstall.py -install (from that
Python's installation folder).
"QuickTest.Application COM ProgID is not registered"¶
UFT One is not installed (or its COM registration is broken) on this machine. Install UFT One 26.1 or 26.3, or run a repair install. The converter's ALM pipeline builds tests through UFT's Automation Object Model and cannot run without it.
IronPython runtime incomplete¶
doctor reports missing files such as IronPython.Modules.dll or the Lib\
standard library next to IronPython.dll under the UFT installation. Expect
this on a fresh install of either supported version: the UFT One 26.1 and
26.3 installers both ship IronPython.dll without these files. Converted
Python tests will import-fail at run time until they are present. Copy the
missing files from the NuGet packages IronPython 3.4.1, IronPython.StdLib
3.4.1, and DynamicLanguageRuntime 1.3.4 into the folder that contains
IronPython.dll, then re-run doctor. An upgrade from 26.1 to 26.3 leaves
files you copied in place, so a machine repaired on 26.1 stays repaired.
uft-migrate license install refuses the license file¶
Nothing was installed, and the edition did not change. The command printed
License not installed: and the reason, and exited 2:
- … was changed after Merito issued it, or Merito did not issue it. Merito Phoenix for UFT ignores it. — the file's details no longer match Merito's signature. Install the file exactly as Merito sent it; if something in it must change, ask Merito for a new file.
- license … expired on and the date — ask your Merito contact for a renewed file.
- … needs a newer version of Merito Phoenix for UFT. — Merito issued it for a later release: upgrade Phoenix, then install it.
- … is not a Merito Phoenix for UFT license file., … is not a valid license: … or … is larger than 64 KB, so it is not a Merito Phoenix for UFT license. — the file is not the one Merito sent, or was damaged on the way. Ask for it again.
- installing for all users needs administrator rights. —
--all-userswrites to the install folder: run the command from a Command Prompt opened with Run as administrator, or leave out--all-usersto install the license for yourself only. - … does not exist. — check the path; put it in quotes when it holds a space.
A license that installs but does not apply to a conversion — one that names other ALM projects, say — is not refused here; see Conversion refused: over the free edition's limit below.
Setup exited with code 10¶
The product is installed, but the license file named with /LICENSEFILE= was
not. Setup's log says why, in its license: lines — the same reasons as the
entry above — and then If a license was installed earlier, it still applies.
If not, the free edition is active. Running Setup again with the same file
fails the same way. Fix the file, then install it for every user from a
Command Prompt opened with Run as administrator:
uft-migrate license install "C:\Deploy\PHX-20261012-3F9A2C.license.json" --all-users
(install.md § Installing a license). Exit code 2 instead
means Setup stopped before installing anything: /LICENSEFILE= named no file,
a file that is not there, or was written without its =.
doctor's license row reads [WARN]¶
The row never fails a check, and the free edition still converts up to 100 test cases. It warns in three cases:
- No installed license file can be used (free edition). The row names
the first one and why — expired, changed, for a newer Phoenix — and counts
the rest;
uft-migrate licenselists them all. An expired one reads The Merito Phoenix for UFT License File for the licensee expired on the date, The free edition now applies, covering conversions of up to 100 test cases. Itsfix:line asks you for a valid license file from Merito, installed withuft-migrate license install. Remove a file you no longer need withuft-migrate license remove <license id>. With a license in use, a file that cannot be used does not make the row warn: the row names it after Other license files:. - The license in use expires within 30 days. Its fix line says when, and what applies after that date: the free edition, or another installed license that outlives it. Ask Merito to renew it before then.
- Phoenix's own license key is damaged. The row says Built-in license key … is damaged., or This copy of Merito Phoenix for UFT has no usable license key, so it accepts no license., and its fix line says Reinstall Merito Phoenix for UFT. Until you do, a license file signed with that key is refused as though Merito had not issued it, so asking Merito for another file would not help.
ALM connection problems¶
"ALM connection timed out" (GUI) or a hang on Connect¶
The ALM server did not answer within 45 seconds. Check:
- the URL form — http://server:8099/qcbin. Only the URL path is retried:
Phoenix tries the URL exactly as typed, and if it carries no path it also
tries <scheme>://<host>[:port]/qcbin and the trailing-slash form. The
scheme and port are used exactly as you type them — if your server is HTTPS
or on a different port, you must type that yourself,
- VPN/firewall path to the server,
- that the ALM site is actually up (open the URL in a browser).
"Unable to create TDConnection COM object" when connecting¶
The ALM Client is not installed on this machine. Install it from your ALM
server's Tools page (ALM Client Launcher / Client Registration), then re-run
uft-migrate doctor. doctor reports the same condition as a warning,
"TDApiOle80.TDConnection COM ProgID is not registered".
"The automation object disconnected mid-call"¶
UFT or the ALM client process crashed or was killed while Phoenix was talking
to it. Close stray UFT.exe processes (Task Manager) and re-run the command in
the same run folder.
- Filesystem runs resume with
--resumeunder the same run id, but only while the interrupted run is still marked as running. - ALM conversions do not need
--resume. Re-run with the same--run-idand the same options. If the interrupted conversion's wave is still open, the re-run continues it, with or without the flag, and first checks any test it may have left half-written (see Native crashes and interrupted ALM conversions below). After a run that finished — completed, or aborted and rolled back —--resumeis refused with exit code 2, so leave it off. Either way the conversion carries forward every asset an earlier run of that run id uploaded and verified, provided the server still holds its complete Python payload. A carried-forward test still serves as a callee, so a test that calls it is converted as usual. The exception is a run folder whose journal an earlier version of Phoenix wrote: see "that callee has no conversion record in this run" below.
During an ALM conversion Phoenix already retries this kind of fault up to twice per asset, killing UFT between attempts — but only while that test's own upload has not started, because a retry after a partial upload would re-run a destructive write.
The ALM session drops during a conversion¶
Before retrying an asset, Phoenix checks whether the ALM session is still alive.
If it is not, Phoenix reconnects and retries the asset, and migration_log.txt
records alm-session-reconnect. If the reconnect fails
(alm-session-reconnect-failed), or the test's upload had already started, the
run aborts — reconnecting first, so the rollback of this run's uploads can
still reach the server. Once ALM is reachable again, re-run the conversion with
the same run id and without --resume.
"ALM discovery failed: …" The analysis or conversion stopped at its first¶
step, discovery, which logs in to ALM in a process of its own and lists every
test in the project's Test Plan. It could not finish, so the run stopped instead
of going on with a partial scope. This run analyzed, converted and wrote
nothing. When the run continued an unfinished conversion wave — a relaunch after
a crash or after a planned restart to free memory, or a resume — it stops the
wave instead, with wave-stopped and the reason discovery-failed (see The
conversion stopped and stays open below): the tests the wave converted earlier
stay converted, and one may be half-written, so run the same command again as
soon as you can; it retries discovery.
Login. When the message goes on with ALM login failed during Login(username, password)., ALM refused the user name or password. Phoenix does not try again, so a wrong password costs one failed login, not two, where your ALM counts them towards locking the account. Check the user name and password, then run again.
Everything else is retried once before you see it. The message says where discovery stopped:
- InitConnectionEx failed for … or ALM Connect(domain=…, project=…) failed. — discovery could not reach the ALM server, or open the domain and project after logging in. Check the ALM URL, the domain and the project, and that the server is up.
- Test Plan folder '
': — listing that folder's subfolders or tests, or reading one of them, failed with the error the ALM client returned. The message can also name the project's test list, which could not be read.failed: - the Test Plan walk under 'Subject' missed N test(s) that the project's test
list places there:
in ' — the walk came back without them, and nothing reported an error.', … - the Test Plan walk and the project's test list … differ: the walk found N test(s) the list does not have — the two listings disagree. A test created or deleted while discovery ran does that too.
- the discovery process crashed (exit code …) without an answer, or did not answer within 600 s and was stopped — the discovery process itself died or hung, wherever it was.
For these, Phoenix has already run discovery a second time, a minute later, in
a new process with a new ALM session: migration_log.txt holds the warning
alm-discovery-retried, whose reason says why — for a process that died,
its exit code or the time limit — and a progress line that announced the
wait. What to do:
- Run the same command again. A short fault in the ALM server or the network passes, and each run starts discovery afresh.
- If it fails again on the same folder or the same tests, open that folder in the ALM client with the same account: check that it opens and lists its tests, and that the account can read every Test Plan folder. Check the ALM server's health and its logs for the time of the failure. If the discovery process keeps crashing, Event Viewer (Windows Logs > Application, events 1000 and 1001) names the faulting module (advanced_troubleshooting.md §9).
- If it still fails, collect diagnostics for Merito support (see Collect
diagnostics for Merito support below). The bundle carries the run folder's
migration_log.txt, where each discovery that reached the Test Plan leaves onealm-discovery-walkline: the folders it walked, the tests it saw in each top-level folder, what it skipped, the result of the check against the project's test list, and the error. It also carries the discovery process's own error in full, with the ALM client's error code, from the process logs.
A conversion also runs discovery a second time when it succeeds but comes back
without tests the signed-off analysis covered; if they are still missing, the
pre-flight gate refuses the run as analyzed-but-not-selected
(advanced_troubleshooting.md §4).
A warning alm-discovery-folder-unreadable in migration_log.txt is not a
failure: the project's list holds the tests it names, the walk did not return
them, and reading their folder failed twice, so discovery could not tell
whether they belong in the run. It counted them and carried on, and the
executive summary's Next Steps name them too. Look them up in ALM: a test in
no Test Plan folder (Unattached) is never part of the conversion; a test
inside the Test Plan should have been found, so run the analysis again and
check that it is listed.
Login succeeds but the domain list is empty¶
The account authenticated but has no domain visibility. Ask your ALM administrator to grant the user access to the target domain/project — this is an ALM permission, not a Phoenix problem.
Conversion problems¶
Conversion refused: over the free edition's limit (license-limit)¶
The conversion has more test cases than your edition converts — more than 100
in the free edition — and no installed license covers it, so no test was
converted, backed up or changed, and nothing was written to ALM. Phoenix
updated only its own run files and logs (on ALM it also signed in and read
the Test Plan, to count the test cases). The Migration
Console says Scoping required at Step 5, and Next stops with Scoping
Required; Run Conversion or Convert Project stops with Conversion
Blocked — Scoping Required. The command line prints
"status": "license-limit", and a message that begins Conversion refused.
No test was converted, backed up or changed., and exits 2.
- Check the count. The
licensingblock in the command's output, and in the analysis'sscan_report.json, givestest_casesand thelimitthat applied; the scoping summary shows the same. The count covers the whole ALM project, or every test under the run's source folders, before any test is parked or excluded, so parking tests or adding Path Exclusions does not lower it (licensing.md § How test cases are counted). The one exception is on disk: tests under folders namedout,.gitor__pycache__, which the default Path Exclusions leave out, count only when the run's Path Inclusions and Path Exclusions keep them. The count can be higher than Assets in Scope. On disk, also check for copies the count does not recognize as Phoenix's own: an old<name>.bakbackup whose converted test was moved or deleted counts as a test of its own. Move it out of the run's source folders — it may be your only copy of the original VBScript test — or delete it only if you are sure you have another copy. - Without a license: press Open Scoping Summary on Step 5, and request a consultation on Merito's consultation request form, which the message names. Install the license Merito sends (licensing.md § Installing a license); you do not have to run the analysis again.
- With a license: read why it did not apply. In the free edition, the
console's dialog lists each unused license under Merito Phoenix for UFT did not use
the installed license:, the command line puts the first reason in its
message and all of them in
license_problems, anduft-migrate licenselists every license file with its reason. A license applies only while it has not expired; to the ALM projects it names, by the server name it lists (reached by another name, a server is another server: ask Merito to add the name you use); and to the Windows user it was installed for, unless it was installed for all users. Over a license's own limit, ask Merito for a larger license.
The limit never stops you finishing, rolling back or restoring a conversion
that is already under way, and the analysis runs at any size. One exception
is an interrupted filesystem conversion whose source folders have since
gained test cases beyond what your edition converts: it is refused
after it has rescanned them, and it can no longer be resumed, so run it
again without --resume once the count is within the limit
(usage.md § The free-edition limit). An ALM refusal leaves the
analysis in the run folder as it was, so Step 5 keeps its reports and
Convert Project works once a license is installed.
Access to the path 'C:\Windows\SysWOW64\out\...' is denied — the whole run fails¶
The conversion stops on the first test with an error like:
AOMError: AOM Test.SaveAs(C:\Windows\SysWOW64\out\<run id>\alm_aom_work\test_<id>_build\<test>) failed:
... 'OpenText Functional Testing', "Access to the path 'C:\Windows\SysWOW64\out\...' is denied"
and the Migration Console's failure dialog reads, for example, "Conversion failed: 116 of 116 assets did not convert." followed by one line per status — "115 × not-attempted" (with an example asset) and "1 × aom-build-failed". The executive summary says the same thing as "116 of 116 ALM asset(s) did not convert (115 x not-attempted, 1 x aom-build-failed)". ALM conversion is all-or-nothing, so the first failure stops every remaining asset.
Cause: Phoenix was launched from C:\Windows\System32. Every run folder —
reports, logs, and the per-test build area alm_aom_work — is written to
out\<run id>\ under the directory Phoenix was launched from. An
Administrator PowerShell or Command Prompt window opens in
C:\Windows\System32, and because Phoenix runs on 32-bit Python, Windows
redirects that folder to C:\Windows\SysWOW64. That location is protected, so
UFT cannot save the first rebuilt test there.
The same failure, launched from the install folder. C:\Program Files
(x86)\Merito\Phoenix for UFT is no more writable than System32, so
double-clicking bin\uft-migrate-gui.cmd in Explorer produces the same denial
with the install folder in the path. Launch from the Start Menu shortcut or a
writable folder instead.
Changing Output Root does not fix it. Output Root only controls where filesystem conversions write converted tests; the run folder always stays under the launch directory (see gui_field_guide.md).
Fix: launch from the Start Menu shortcut (Start Menu > Merito > Merito Phoenix for UFT). It always starts in the profile folder of whoever launches it, so it cannot hit this problem. If you launch from a console instead, change to a writable folder before launching:
cd $env:USERPROFILE
uft-migrate-gui
A warning sign before you start a run: the Migration Console remembers its
settings in out\.uft-migrate-gui-cache.json under the launch directory. If it
opens with your ALM URL, user name and other fields blank, it was launched from
a different directory than last time — close it and relaunch from the right
folder.
A test converts cleanly but fails at first run in UFT¶
NameErroron a VBScript function name (for exampleCInt,Left,Trim): the test was converted with an earlier version of Phoenix. Re-convert with the current version, which supplies compatibility helpers for the VBScript intrinsic library.RuntimeError: PhoenixVBRuntime.pfl file not found, or it does not contain the helpers this script needs: …: the script installs its VBScript compatibility helpers from the shared libraryPhoenixVBRuntime.pfland found no copy that has them. UFT reports the failure near the top of an action — or of a converted function library (.pfl) — inside the generated# _phoenix_vb_runtimeblock, which follows the library-binding prelude when the script has one, so expect a line number well past 1.- ALM / Test Lab: check that the test is still related to the resource
Resources\UFT Phoenix\PhoenixVBRuntime.pfl(the test's Test Resources in ALM); the relation may have been removed since the conversion. Conversion relates the library before any script depends on it, so a test that was uploaded with this block was related when it was converted — if relating fails, Phoenix leaves that test's helpers pasted in the script (recorded ashelper runtime RELATION ERRORin its conversion notes) or fails the asset before upload. Then clear%LOCALAPPDATA%\Temp\TD_80on the execution host in case an older copy is cached, and run again. - Local filesystem: the file must still be at the absolute path listed in
the Portability Manifest (
FunctionLibraries\PhoenixVBRuntime.pflunder the output root). If the converted tree was moved, re-run the conversion with the final location as the output root. - After a hand edit and a later conversion: a conversion rewrites the
shared library only when it lacks a helper the test being converted needs.
The rewrite keeps every entry you did not edit, but not your edits. An
edited entry is put back as Phoenix wrote it when this version still ships
that helper unchanged, and dropped when it does not; anything else you
added to the file is lost. On ALM the conversion notes then say
EXISTING CONTENT REPLACEDand name the saved prior copy. Re-convert the tests that name a dropped entry. On ALM, conversion is whole-project, and a conversion under an earlier run's ID — including the Migration Console's defaultDomain-ProjectID — skips every test that run already converted and is still Python on the server, which is exactly the tests you need to rebuild. Run analysis and then conversion under a new run ID (a new Analysis Run ID in the Migration Console,--run-idon the CLI). If a pasted copy was converted while its original was parked or converted differently, first copyalm_aom_work\alm_rollback\pasted_copy_owner_maps.jsonfrom the earlier run folder to the same place in the new one (limitations.md § ALM environment boundaries). On a filesystem conversion, convert those tests again with Overwrite Policybackuporoverwrite, or into a new output root: the default,fail, refuses to overwrite what is already there. - "unterminated string literal" reported by UFT at line N (UFT 26.1 only —
UFT 26.3's script engine,
ScriptExeEngine.dll, no longer contains the validator's error text, and the converter's workarounds are harmless there): UFT 26.1's pre-execution validator synthesizes a malformed error for lines it thinks call a test-object method without parentheses; because that synthesized statement does not compile, any flagged line — with or without quotes in it — kills the whole action. The converter works around the known cases (FSO methods,.Valueassignments,ExpandEnvironmentStringscalls, bare.Countreads on collections, assignments to members of UFT's reserved objects such asSettingandDataTable, and parentheses enforced on known UFT methods such as.Activate). If you hit a new one, report the exact line — do not hand-edit the.ptson the server. - UFT runs an older version of the test after you re-uploaded or reverted
it: UFT caches extracted tests under
%LOCALAPPDATA%\Temp\TD_80. Phoenix purges this cache automatically (on by default;--no-purge-uft-cacheturns it off), but only for the Windows user running Phoenix on that machine. On every other machine that runs the tests — Test Lab execution hosts, other engineers' workstations — delete%LOCALAPPDATA%\Temp\TD_80before the next run. The command is in advanced_troubleshooting.md § Stale UFT test cache (TD_80). - A converted test reads
No Runin Test Lab right after the conversion, and the ALM execution log says Unable to open … Test not found: UFT read a partly deleted copy of the test from TD_80, because a process still held files in it when the cache was purged — usually a leftover UFT Remote Agent (UFTRemoteAgent.exe) from an earlier Test Lab run. On the machine running Phoenix, the asset's notes carry a[warning] UFT test extraction cache (TD_80)note; the Executive Summary's Next Steps also says what to close when the cache was still not cleared at the end of the run. The converted test in ALM is fine, so this is a false failure: close UFT One, endUFTRemoteAgent.exein Task Manager if it is running, delete%LOCALAPPDATA%\Temp\TD_80, and run the test again. Phoenix stops a leftover agent itself when a conversion's purge cannot delete every file after UFT One is closed, and says so in the same note (advanced_troubleshooting.md § Stale UFT test cache (TD_80)).
A converted test behaves differently with no error reported¶
- You changed which function library a test links after it was converted,
and it now runs the old library's functions — or the new library's
functions go missing from the second iteration of a multi-test Test Lab run
onward. Library links are written into the converted script at conversion
time, and a later relink does not update them. Change library content
rather than links, or convert again under a new run ID and clear
%LOCALAPPDATA%\Temp\TD_80on every execution host. If a pasted copy was converted while its original was parked or converted differently, first copyalm_aom_work\alm_rollback\pasted_copy_owner_maps.jsonfrom the earlier run folder to the same place in the new one. See limitations.md § Library links are fixed when a test is converted. - A test takes roughly 6-15 s longer per run than its VBScript baseline
when it calls a helper that walks every running process (a
GetObject("winmgmts:").InstancesOf("Win32_Process")loop that reads.Nameon each returned object), about 4-12 s per call. This is expected after conversion, and nothing fails. Change the source helper to a filtered query —ExecQuery("Select ... from Win32_Process where Name = '<exe>'")— before converting. See limitations.md § A source helper that scans every process runs slower after conversion.
"Blocked unsupported construct" / status blocked in the ALM pipeline¶
The converter refuses to upload tests with unresolved blockers (fail-closed
policy). The report lists each blocker (construct blockers with their source
line; the others name the action, cross-test reference or error). Options:
1. Remediate the construct in the VBScript source and re-run. A custom mapping
rule does not clear this blocker: mappings rewrite the converted text after
the blocker has already been recorded, so remediate the source instead.
2. Expert override (CLI-only): --allow-blockers uploads anyway and records
the override in the run notes. The blocked statement is replaced by a
comment in the uploaded Python (# BLOCKED: unsupported …), so whatever
it did no longer happens — use this only when you have verified the blocked
lines are unreachable or harmless. The GUI has no override — park deferred
assets on Step 5 instead.
--allow-blockers covers best-effort construct blockers only. Two classes
are data-integrity stops that keep status=blocked even with the flag set:
converted output is not valid Python— the converted text will not parse. It would upload and verify clean and then be dead the moment UFT runs it. The--dry-runanalysis path applies the same stop, and the filesystem path refuses it as a tier of its own (not overridable by strictness either).- A cross-test reusable-action reference that cannot be retargeted to the converted callee's renumbered layout — building anyway would upload a caller natively bound to the wrong callee action.
For either, remediate the source or the call chain; the flag will not move the run. The second class has its own entry below for the message that callee has no conversion record in this run.
Constructs that remain intentionally unsupported: Execute/Eval as a
statement (dynamic code) — at strict and at the shipped default standard
strictness the converter names these as blockers. At --strictness permissive
it records a warning instead and emits a raise NotImplementedError(...) stub
in their place; that stub is valid Python, so the syntax gate passes it and the
test fails only when UFT runs that line. ALM conversions are forced to strict,
so they always block there.
GoTo <label> (including the inline If … Then GoTo <label> form), On Error
GoTo <label> and VBScript classes (Class…End Class, Property Get/Let/Set)
are recognized by no construct detector, so no blocker names them and a scan
whose only issue is one of them still reports go_no_go: go — but they are
not silent. The converter emits them verbatim (Class(Cart),
Property(Get Bar), On Error GoTo Handler), the result is not valid Python,
and the syntax gate refuses the asset with a generic converted output is not
valid Python blocker before any AOM build or ALM write — at every strictness
level, and not overridable. The one construct that genuinely reaches UFT is
Eval used inside an expression (x = Eval("…")): it converts to a call to
an undefined Eval, which parses cleanly, uploads and verifies clean, and
raises NameError only when UFT runs the test. Sweep the source for all of
them before converting; see limitations.md § Not detected
before conversion.
ExecuteFile is refused the same way, and the refusal is decided from the
statement kind alone — dynamic library loading from script has no safe
automatic translation. Phoenix does resolve each test's linked ALM Test
Resources, but that lookup plays no part in this decision, so linking the
library in ALM does not clear the blocker. (ALM conversions are forced to
strict, so it is always a hard blocker there; a custom mapping rule cannot
clear it either — mappings are applied at emit time, after the blocker is
recorded.) Remediate by deleting the ExecuteFile line from the source and
relying on the linked-resource path instead: function libraries linked as ALM
Test Resources are downloaded, converted once to a Python Function Library
(.pfl), and linked to each converted test automatically (shared resource —
not inlined into actions), so their functions are already in scope with no
loader line and no import.
Action-level parameter definitions (Action Properties → Parameters) and
test-level definitions (File → Settings → Parameters) are both harvested from
the legacy test and re-authored on the converted test. The main flow (Action0)
has no parameter surface of its own, so its Parameter() reads are satisfied
by the test-level definitions, and that resolved set is authored onto the
rebuilt test's main flow. Harvesting needs UFT, so a blocker is raised only in
a Deep analysis (Analysis Depth = Deep) or a conversion; the default
Standard analysis never opens UFT and only notes that the definitions will be
harvested at conversion time. The blocker is raised only when a referenced name
matches neither an action-level nor a test-level definition (or when the
harvest itself fails) — add the definition in UFT, or replace the read with a
DataTable/Environment lookup. Test-level default values are carried, but
test-set runtime overrides do not propagate through the AOM main-flow
indirection.
See supported_versions.md and limitations.md.
"that callee has no conversion record in this run"¶
A conversion stops on a test that calls another test's reusable action. The
asset is blocked and its error reads cross-test reference '--allow-blockers does not clear it. There are two causes:
- The callee was not converted in this run. Its own conversion failed, it is not part of the run, or it was not ordered ahead of its caller — callees convert first, in the order the analysis in the same run folder gives. Deal with the callee first (its own entry in the report says why), and make sure the analysis was run under this run id before you convert.
- The callee was carried forward from a journal that an earlier version of
Phoenix wrote. That journal did not record the converted layout. In
alm_aom_results.jsonthe callee showsresumed: trueand a note that the journal record it was carried forward from carries no conversion maps. Run the analysis again under a new run id (in the console, enter a new Analysis Run ID on Step 5 and run Analysis), then convert in that run folder so caller and callee convert together. Keep the old run folder: itsalm_rollbackfolder holds the pre-conversion originals. If a pasted copy was converted while its original was parked or converted differently, first copy that folder'spasted_copy_owner_maps.jsonto the same place in the new run folder (limitations.md § ALM environment boundaries).
"the source test shared object repositories could not be harvested … refusing to rebuild without them"¶
An asset ends aom-build-failed with an error that reads the source test
shared object repositories could not be harvested (
The run treats the failure as transient: it converts the test again, up to
twice. If it still fails, the conversion stops like any other failed asset and
rolls back what it uploaded (see "Post-upload verification failed" below for
how to read the statuses). Check UFT's health and licenses on the conversion
machine (uft-migrate doctor), then run the conversion again. If the same test
keeps failing, open it in UFT and check that its repository associations
(Resources → Associate Repositories) and the .tsr resource itself load.
"shared object repository NOT carried into the rebuilt test … refusing to upload the test without it"¶
An asset ends aom-build-failed with an error that reads shared object
repository NOT carried into the rebuilt test:
The run first converts the test again, up to twice, noting pre-upload build failure with an unrecognised message; retrying it as transient. If it still fails, the conversion stops like any other failed asset and rolls back what it uploaded. Resource relations the conversion had already added to the test in ALM, such as the one to the helper runtime library, stay in place: a rollback does not remove relations (see alm_safety.md).
Open the source test in UFT and check that the repository loads
(Resources → Associate Repositories) and that the .tsr resource exists in
ALM at the path it names. Check UFT's health on the conversion machine
(uft-migrate doctor), then run the conversion again. If the same test keeps
failing, collect a diagnostics bundle (uft-migrate diagnostics collect) and
send it to Merito with the test's name.
"[warning] the source test's files associate shared object repository … which UFT reports for none of its actions"¶
A converted test's notes hold [warning] the source test's files associate
shared object repository
A test's files in ALM can name a shared object repository that none of its actions uses: ALM keeps the files of an action that was deleted from the test or replaced, and they still name the repository that action used. Phoenix carries the repositories UFT reports for the test's actions. A repository only the files name is reported on the test rather than refused, because refusing it would stop the whole conversion over a repository the test does not use.
Open the converted test in UFT and check its repository associations (Resources → Associate Repositories). If one of its actions does find its objects in that repository, associate it there again. A test that an earlier version converted without its repository, and that you convert again, reports it this way too: see limitations.md § Shared object repositories on caller tests (fixed in 1.3.4).
"Post-upload verification failed" (status upload-verify-failed)¶
After every upload Phoenix re-downloads the test and compares it with the built
payload; files the server did not overwrite are deleted and re-uploaded once,
then verified again. A mismatch that survives that repair stops the whole run:
every later asset is recorded not-attempted, and Phoenix restores every asset
this run uploaded — this one included — from its pre-conversion snapshot. On
version-controlled projects the checkout is abandoned as well, which returns the
server to the last checked-in version.
Check each asset's final status:
rolled-back— the original VBScript scripts are back on the server, but the test's resource relations are not reverted: a test this run had already uploaded and verified stays related to the converted.pflinstead of its original.qfl. Re-relate the.qflin ALM before running it from Test Lab (see alm_safety.md § What a restore does not undo), then fix the cause and re-run the whole conversion.rollback-failed— do not run the test. Restore it withuft-migrate restore … --wave <wave>, where<wave>is the asset'swaveinalm_aom_results.json(see alm_safety.md § Rolling back), or from ALM version history or your own backup, then report the issue with a diagnostics bundle (see Collect diagnostics for Merito support below). Until every such test is restored or settled, the next conversion in that run folder stops and prints the restore command for each one.
Native crashes and interrupted ALM conversions¶
An ALM upload conversion runs under a crash supervisor, and each all-or-nothing conversion is a conversion wave that can span several attempts. advanced_troubleshooting.md §9 explains both; alm_safety.md § Interrupting and resuming says what an interruption leaves behind.
Every uft-migrate restore command these messages print is complete, and runs
from any folder: it carries the run id and --output-root with the full path
of the folder that holds the run folder. A command that writes to ALM reads the
password from UFT_MIGRATE_ALM_PASSWORD, and the message says to set it first.
Run several in the order given, which is callers first.
The conversion process crashed¶
The Migration Console's status line reads The conversion process crashed (…), then Cleaned up after the crash: … and Relaunched the conversion (attempt N, …). Windows ended the conversion process (a native crash); the supervisor recorded it, cleaned up and started the conversion again. The new attempt checks any test the crash may have left half-written against the copy the wave froze before changing it, restores it from that copy if it differs, and carries forward the tests already converted.
- It recovered. The run carries on and ends as usual. Conversion Complete
adds how many crashes were recovered. The executive summary's Next Steps say
how many were relaunched automatically and whether any struck after a
payload write began, and name the evidence folder
crash_recovery\<wave>\; each affected asset carries a[crash recovery]note, listed under Crash Recovery Notes on the assets page (analysis_assets.html) and inscan_report.md. The assets converted before the crash are reported as converted by an earlier attempt of this run, with what their conversion recorded, and the report's total time covers every attempt (not the time between them). Nothing needs doing, but the evidence does not stay forever: Phoenix deletescrash_recovery\<wave>\itself once two later conversion waves in this run folder that wrote a test have closed (a launch that wrote no test, such as one the pre-flight gate refused, does not count, even if it replaced a function library: library writes are not recorded in the journal), so copy it elsewhere if your records need it. A memory dump is never in that folder, because a dump may hold the ALM password: if Windows wrote one, it is in the Windows crash-dump folder that the attempt'scrash.jsonnames ("wer">"dump"), and Windows replaces the oldest dumps there (it keeps 10 by default). - Recovery stopped at the crash budget — the third crash while the same
test was in flight, the wave's crashes reaching its crash budget, or the
second in a row outside any test. The wave's crash budget is 6 plus 2 % of
the tests it has begun converting, rounded down (7 at 50 tests, 12 at 348);
each relaunch message states it and how it was reached. A wave an earlier
version of Phoenix opened keeps a fixed 6. The supervisor aborts the wave:
the test that was in flight, if any,
ends
process-crashed(report category Crashed the conversion process repeatedly), and everything the wave wrote is rolled back from its copies, callers first; each asset's status says whether its restore worked (rolled-backorrollback-failed). A wave with nothing to roll back — it wrote no test, or every test it wrote is already back on its copy — is closed without an abort. Conversion Failed lists the outcome by status, and the executive summary's Next Steps say why the wave was aborted and whether its rollback finished. If the test that crashed uses a function library — its own orPhoenixVBRuntime.pfl— its notes add that its relation toPhoenixVBRuntime.pfland the shared.pfllibraries its conversion wrote are not reverted — exactly which, when the crash came after its upload began, otherwise that it may have — and where the copies saved before they were replaced are. Every asset the rollback restores says the same in its own rollback note. Collect diagnostics for Merito support (see Collect diagnostics for Merito support below) — the bundle carriescrash_recovery\<wave>\,crash_breadcrumbs.log,migration_log.txtandresume\, which matter most, with Windows' crash reports — and re-run the whole conversion once the cause is known. - It crashed during a rollback. Finishing an interrupted rollback is not
automated. The message lists every test still to restore, callers first,
and up to three numbered
restore --wavecommands; the full list, in order, is incrash_recovery\<wave>\restore_commands.txt, which the message names. Run them, then run the conversion again with the same inputs. - It ended without recording its result. A conversion process that exits — even with exit code 0 — without recording its result is never reported as a success: the supervisor says what happened and exits with a non-zero code. Unless every asset had already finished, the wave stays open, and running the conversion again continues it. If every asset had finished, the message says so, and running the conversion again carries them all forward and only records the result or writes the reports.
The conversion process restarted itself to free memory¶
migration_log.txt shows planned restart of the conversion process after test
N …, then Restarted the conversion process to free memory (attempt N, planned
restart K of at most 100 in this session). This is no crash and uses no crash
budget …. The conversion process is 32-bit, so it has at most 2 GB of address
space; once it has finished at least 25 tests in one attempt and its memory is
high (1,100 MB of private memory, or 700 MB or less of address space left),
it ends itself between two tests and the supervisor starts it again. The tests
it converted are carried forward without being read from ALM again, and nothing
is in flight, so nothing needs doing. No crash is counted and no evidence is
collected. If the process crashes while shutting down after it decided to
restart, the log says so (… then crashed while shutting down …): that crash
is recorded with its evidence but still uses no crash budget, and the next
attempt checks the finished tests in ALM before skipping them. In the unlikely case that a single session needs more than 100 such
restarts, it stops instead with planned-restart-limit: the wave stays open,
and running the conversion again with the same Run ID continues it.
The conversion stopped and stays open (wave-stopped)¶
The conversion exits 2 with a result whose status is wave-stopped (or
journal-unwritable), and its message starts Conversion stopped (alm_wave_stop.json in the
run folder. Conversion Failed shows the message in full, first, and names
alm_wave_stop.json. The message names the test, the copy to restore it from
and numbered next steps, with every command written out. Take them, then run
the conversion again with the same inputs (in the console: Convert
Project, either answer to Resume Previous Run): the wave continues.
| Reason | What it means | What to do |
|---|---|---|
journal-unwritable |
The conversion journal, resume\alm_test_results.ndjson, could not be written (disk full, permissions, a file lock), so the conversion stopped before its next ALM write. A program that holds the file for a moment — a backup or sync agent, an antivirus scanner — is waited out for about 8 seconds first. |
Fix the cause and run again. |
snapshot-failed |
The copy of a test that the conversion keeps before changing it could not be made in the run folder — the disk is full, for example, or a program holds a file in it. Nothing was written to ALM for that test. | Free disk space (or fix the run folder's permissions, or close that program), then run again with the same inputs: the wave continues where it stopped. |
restore-failed |
After a crash, a test that may be half-written differed from the wave's copy, and restoring that copy failed. | Run the restore --wave command in the message, then run again. |
restore-failed-earlier, rollback-interrupted, rollback-incomplete |
A restore failed in an earlier attempt; or the process stopped while rolling the wave back; or the rollback ended with tests still not back on the wave's copy. These tests may hold converted or half-written payloads. | Run each restore --wave command in the message, in the order given, then run again. For restore-failed-earlier the message also gives the --accept-current-state command, to settle tests you have inspected as they are. |
reconcile-failed |
A test that may be half-written could not be found in ALM, or downloaded, to check it. | If ALM was unavailable, run again once it is back. Otherwise restore the test with the command given, or — when it could not be found — inspect it in ALM and settle it as it is with the --accept-current-state command given. |
snapshot-invalid |
The copy the wave froze of a test is missing or damaged, so the test cannot be restored automatically. | Inspect the test in ALM; if it is not intact, put it back from your ALM backup or version history. Then settle it with the --accept-current-state command in the message — it sets the damaged copy aside, and the wave freezes a new one from what ALM holds — and run again. Until the test is settled the conversion stops here every time. |
snapshot-drift |
A test changed on the server after this wave first saw it, and the wave may already have written it, so the wave's copy no longer describes it. When the journal shows the wave never wrote that test — it changed after a Cancel, say, before its upload started — there is no stop: the wave freezes its copy again from what ALM holds, keeps the old copy beside it, notes this on the test and logs alm-wave-snapshot-refrozen. |
Inspect the test, then either put it back to the wave's copy with the restore --wave command in the message and run again, or keep the change: close the wave with the --abandon-wave command in the message (refused while any test in the wave may be half-written) and convert again — a new wave starts from what the server holds now. |
wave-scope-changed |
The set of tests the conversion finds changed after the wave started. This attempt wrote nothing to ALM; tests the wave converted earlier stay converted. Tests the wave started with that are missing now can come from a transient fault while ALM listed the Test Plan; Phoenix already ran discovery a second time before it stopped (alm-discovery-retried). |
Run the conversion again with the same inputs: it runs discovery again. Only if the same tests are missing again, check that the path filters and exclusions are the ones the wave started with, and whether those tests were moved or deleted in ALM. When tests were added instead, or to convert the new scope, close the wave with the --abandon-wave command in the message, then run the analysis and the conversion again. |
discovery-failed |
The wave was continuing — after a crash, after a planned restart, or on a resume — and discovery, which lists the project's tests first, failed even after its retry (ALM discovery failed: … in the detail line). This attempt wrote nothing to ALM and checked nothing yet; tests the wave converted earlier stay converted, and a test a crash interrupted may still be half-written. | Run the same command again: it retries discovery, then continues the wave, checking that test first. If the detail says the login failed, correct the password first (it is not one of the wave's inputs). Until the wave has continued, do not run its tests. See "ALM discovery failed: …" above for the other causes. |
legacy-in-flight-unverified |
A test that a Phoenix 1.1.4 or earlier run was converting when it stopped could not be proven unchanged since. | Restore it with the plain restore command in the message (no --wave), from the first copy this run folder kept of the test — the message says when it was saved; it can be older than the run that stopped, so check it is the version you want — or inspect the test and settle it with the --accept-current-state command given; then run again. |
Any other reason is explained the same way in the message itself.
--accept-current-state and --abandon-wave make no change in ALM; they
only update the run's journal. The messages print them in this form:
uft-migrate restore --output-root "<folder that holds the run folder>" --from-run "<run id>" --wave <wave> --alm-test-id <id> --accept-current-state
uft-migrate restore --output-root "<folder that holds the run folder>" --from-run "<run id>" --abandon-wave <wave>
The first records that you inspected each named test and accept it as it is
now, which settles it; the wave's copy of it is set aside, so the next attempt
takes the accepted state as its starting point. Use it only after checking the
test in ALM. The second closes a wave without converting further. It is refused
while any test in the wave may still be half-written, and the refusal lists the
restores still owed, callers first, and the --accept-current-state
alternative. Tests the wave converted stay converted, and the next conversion
carries them forward.
"Another Phoenix process … is working in the run folder"¶
A conversion, an analysis or a restore is already running in this run folder,
and only one may work there at a time. Nothing was written. Wait for it to
finish (watch migration_log.txt in that folder), or stop it, then run again.
The lock is released when its holder ends, however it ends; the file
resume\phoenix_run.lock stays behind and is harmless. If the message says the
lock file could not be opened, check the run folder's permissions. In the
Migration Console the same message appears as Run Folder In Use when you
press Run Analysis or Convert Project, and the console then leaves the
run folder exactly as it was.
"conversion wave … is not settled" or "… was started with other inputs"¶
The conversion was refused before anything was written.
- Not settled. An earlier conversion wave in this run folder may have left
the named tests half-written or half-restored, and a new wave would take that
damage as its starting point. The message gives one numbered
restore --wavecommand per test, callers first, and the--accept-current-statecommand that settles them as they are once you have inspected them in ALM. Run those, or run the original conversion again to continue that wave, then run your conversion again. - Other inputs. An unfinished wave is open in this run folder, and this
launch differs from the one that started it: any change to the command line
other than
--run-id,--resume,--failed-onlyand the value of--passwordcounts — in the console, any selection that changes the command Review Command shows. If that wave has not written any test yet — it was canceled before its first upload, for example — it is not refused: it is closed (outcomesuperseded-no-writes), the run says so, and the new launch starts a new wave. A wave that has written a test is refused: the message says which options differ and gives the--abandon-wavecommand that closes it. Run the original command again to continue the wave, or close it with that command once nothing in it is half-written.
ALM version control and locks¶
A locked asset was converted anyway (entity-lock-not-cleared-proceeding)¶
This is by design: a lock never fails a conversion. Phoenix gives the lock a
10-second grace period to clear on its own, tries to release it, and then
converts and overwrites the asset either way. That is safe because an ALM
lock does not block ExtendedStorage.Save — the write that carries a test's
payload (Script.pts, Test.tsp, the .usr); it blocks only entity
metadata writes (SetField/Post), which the upload path already treats as
optional. Failing instead would leave the project half Python and half
VBScript, which breaks cross-test action chains.
UnLockObject() releases only your own lock — against another session's it
returns cleanly and does nothing — so revoking a foreign lock means deleting
its row from the project's LOCKS table through the OTA Command object,
which ALM disables by default. Where that is available the run logs
entity-lock-force-revoked; where it is not, it logs
entity-lock-not-cleared-proceeding and the conversion completes regardless.
Either way the asset carries a note naming the lock holder. When Phoenix can
read the project's LOCKS table — the same OTA Command access that revoking
a lock needs — the note also gives the holder's machine, ALM session id, lock
time and last-active time. Otherwise it names only the user.
Nothing needs re-running. What it does mean: if someone was still editing that asset, their work has been overwritten and their ALM client may hold a stale copy — have them close and reopen the test. Run conversions in an agreed window with the project empty to avoid this entirely.
An asset fails as "Version control blocked" (status vc-blocked)¶
On version-controlled projects Phoenix undoes any pre-existing checkout
before converting (the server reverts to the latest checked-in version, which
is what gets converted). Undoing another user's checkout requires the
connected ALM user to hold the "Manage checkouts"-equivalent permission.
Grant that permission to the migration account — or have the holder check in
or undo their own checkout — then run the conversion again under the same run
id. Do not add --resume: it is refused after a run that failed, and a
vc-blocked asset aborts the run. The aborted run rolled back what it had
uploaded, so those assets are converted again; any asset an earlier run already
uploaded and verified, and that is still Python on the server, is carried
forward automatically.
Where to see who holds checkouts and locks¶
The analysis report's Version Control & Locks section (same name in the markdown summary) lists how many assets are checked out or locked and names the holder of each — the first 100 of each kind, though the counts always cover all of them. It is the chase list to clear before a conversion. That section is written only when the project is version-controlled (at least one analyzed asset reports version control enabled); on a project without version control it is omitted entirely, and a lock holder is then named only in the per-asset run note described above. Analysis itself performs no version-control writes, so it is safe to run at any time.
Runtime errors in converted tests¶
These appear when a converted test executes. Most are runtime issues in the test's environment or object repository, but check the conversion notes first: some documented limitations show up this way, and so does, for a test converted by 1.3.3 or earlier, a shared object repository that was not carried (step 1 under Cannot identify the object below). Two rules first:
- Prefer running converted ALM tests from ALM. That is how they will be
run in production — from your existing Test Lab sets in the ALM
client, or via the CLI-only support lever
--run-via-almwhen the run needs to land in the Phoenix report (there is no GUI run-from-ALM option). Opening a converted test from ALM in UFT One and pressing Run is a legitimate spot check for a single test — it is what the CLI itself recommends, and it is the only check available for filesystem conversions. Two caveats when you do: purge%LOCALAPPDATA%\Temp\TD_80first, because a stale extraction makes UFT execute the pre-conversion build (Phoenix purges that cache before its own Test Lab runs for the same reason); and a resource-resolution failure seen only in a manual run is not automatically a conversion defect — reproduce it from Test Lab before filing it as one. - When one line fails and you skip past it, treat every later error in the same run as suspect until the first failure is fixed — most are consequences, not independent defects.
SystemUtil.Run(...) fails with Error: Exception occurred. (0x-7ffdfff7)¶
Meaning: the executable path in the call does not exist on this machine.
Legacy tests frequently launch sample or line-of-business applications from
era-specific install paths. Phoenix does not rewrite path literals in your test
scripts — converting VBScript to Python translates the language, not
what the script says. A converted test that carries an HP\, HPE\ or
Micro Focus\Unified Functional Testing path will fail SystemUtil.Run
exactly as the VBScript original did on that host. If this error appears:
- Read the path in the error dialog literally and check it in File Explorer.
- Correct the path in the source test, or install the application at that path. A surviving vendor-era prefix is intended behavior, not a converter gap — do not report it as one. (Phoenix deliberately never rewrites these prefixes: a rewrite can collapse a test's own fallback list of install locations into one repeated path.)
- The only path literals Phoenix alters are over-escaped backslash runs. On
the ALM path each one is recorded as a per-asset converter finding naming the
before and after value, and rendered on the Convertible Findings
drill-down (
analysis_convertible_findings.html) thatscan_report.htmllinks;scan_report.htmlitself carries only the rollup count. Filesystem conversions do not surface it at all — the converter raises the warning but nothing carries it into the report, so diff the converted file if you need to see which literals changed.
Cannot identify the object "X" (of class Y)¶
Meaning: UFT's object repository could not match the object's recorded
identification properties against anything currently on screen. A test that lost
its shared object repository during conversion reports a different message —
Cannot find the "<object>" object's parent — which step 1 below covers.
If this test passed under VBScript before conversion, check that baseline
run first. A duration at or just above the object sync timeout that ends in a
Replay Warning on a step that is not an OptionalStep means the
identification failure already existed and was graded as a warning — a
Replay Warning from an OptionalStep is normal and means nothing here. See
limitations.md § Conversion can surface
object-identification failures your baseline hid.
Work through, in order:
- Check this asset's conversion notes. A test converted by 1.3.3 or
earlier may hold
[warning] shared object repository NOT carried into the rebuilt test. If it does, re-associate the repository in UFT (Resources > Associate Repositories) — see limitations.md § Shared object repositories on caller tests (fixed in 1.3.4). A test converted by this version may hold[warning] the source test's files associate shared object repository; if the object belongs to that repository, associate it again the same way. Also review limitations.md § Test-level artifacts not carried: Environment variables, externally linked Data Tables and Record-and-Run settings do not travel with a conversion, and a test can fail at run time for that reason alone. - Was the application actually running? If an earlier line (for example
the
SystemUtil.Runlaunch) failed, this error is a consequence — fix the launch first. - Check the add-ins. Open the test's properties (in ALM, or File >
Settings in UFT) and confirm the add-ins the object classes need are
associated —
UIAWindow/UIA*objects need UI Automation,WpfWindow/Wpf*need WPF, and so on. - Check the repository and highlight. Open the Object Repository, locate the object named in the error, and — with the application running — use Highlight in Application. If highlighting fails, the recorded identification properties no longer match the live application (window titles frequently change across application versions, e.g. an HPE-era title on a rebranded build). Update the object's identification properties or re-record it.
- Verify the script line maps to the repository object. The name in the script line must match a repository object of the same class in that action's repository. A mismatch means the repository association (not the code) needs repair.
Where to look when a run fails¶
A run writes its artifacts under out/<run_id>/; which files appear depends on
the path it took. The HTML pages follow --report-format, except the ALM
drill-down pages (analysis_*.html), which are always written.
| File | Contents |
|---|---|
scan_report.html |
Per-asset blockers and warnings from analysis |
scan_report.json |
The verdict, and in its licensing block the test-case count, the limit and the edition the analysis saw |
scoping_summary.html, scoping_summary.json |
The analysis in counts and summary figures, with no names, paths, identifiers or test code, to send Merito for scoping a license if you choose; written by every analysis |
executive_summary.html |
Verdict, next steps, links to the detail reports, and, when the run recorded them, the run's start, finish and elapsed time (Run Timing, in local time). Written by the run command (filesystem or ALM) and by summarize — not by scan, convert, or ALM analysis |
analysis_assets_failed.html |
Failed assets with their causes (ALM) |
alm_preflight.json |
Why the pre-flight gate refused the run — no ALM writes were made when it did |
alm_aom_results.json |
Per-test ALM pipeline results, incl. blockers and upload verification |
alm_analysis_results.json |
The analysis the pre-flight gate judged the conversion against |
conversion_summary.json |
Machine-readable per-asset outcome of an ALM run — written by ALM analysis as well as by a conversion |
resume/alm_test_results.ndjson |
Per-asset journal — the only record left if the run is killed |
resume/alm_asset_details/ |
What the report shows for each converted asset, kept for a later attempt that carries the asset forward |
alm_wave_stop.json |
Why an ALM conversion stopped and stays open, with the next steps — written instead of a report set |
crash_recovery/<wave>/ |
The crash supervisor's evidence for each conversion attempt, including Windows' crash report when there was a native crash. Deleted automatically once two later conversion waves in the run folder that wrote to ALM have closed (a wave that wrote nothing, such as a launch the pre-flight gate refused, does not count; nothing means no test: such a wave may still have replaced a function library, because library writes are not journaled); never holds a memory dump (crash.json names where Windows wrote it) |
crash_breadcrumbs.log |
One line per ALM call or build step of an upload conversion; the last line of a crashed process names the step it died in |
migration_log.txt |
Structured JSON-lines event log (ALM runs) |
convert_report.html |
Per-file conversion status (filesystem only) |
validation_report.html |
Post-conversion syntax/UFT checks (filesystem only) |
analysis_cli_*.log, run_cli_*.log |
Raw CLI output captured by the GUI |
Two places outside the run folder:
| Location | Contents |
|---|---|
%LOCALAPPDATA%\Merito\UFT Phoenix\logs\ |
One diagnostics log per Phoenix process, JSON lines: what each process was, the errors it met (with the full traceback and the ALM client's error code) and how its child processes ended. A message that gives a reference such as E-20261006T101500Z-7720-41 names an error recorded there in full; quote it to support. Kept 30 days. The ALM password is masked before a record is written: by its value when it is 6 characters or longer, and wherever it follows a name such as password |
out\_support\ |
The support bundles Collect Diagnostics… and the Start Menu shortcut Merito Phoenix for UFT Collect Diagnostics write, each a zip with a folder of the same files beside it; when there is no out\ folder, they go to %LOCALAPPDATA%\Merito\UFT Phoenix\support\ |
When contacting support, quote the version you are running. The Migration
Console shows it on every step, in the bottom-left corner of the dark panel on
the left (Version and the number, with the edition on the line under it; see
gui_field_guide.md § The version line), and
uft-migrate --version prints it. A diagnostics
bundle records it already, in the zip's name, README.txt and
MANIFEST.json. Do not send the run folder: it holds your test sources
(alm_aom_work\) and lacks the process logs, the environment and Windows'
crash reports. Collect diagnostics instead (below).
Collect diagnostics for Merito support¶
Phoenix keeps its diagnostics logs all the time: there is nothing to switch on, and the problem does not have to happen again for you to collect it. You can collect afterwards, even after closing Phoenix: each way below reaches back as far as Phoenix keeps its logs, up to 30 days. When Merito support asks for diagnostics, or a run failed in a way this guide does not explain, collect a support bundle and send it to Merito support. Merito supports the Free Edition on a best-effort basis. For the Licensed Edition, your order form or statement of work sets the support. Merito keeps a bundle you send confidential, uses it only to provide that support, and deletes it within 30 days after you ask (LICENSE section 6.c, which says what Merito may keep). The simplest way first:
- Answer Yes when the failure dialog asks. Conversion Failed ends with the question Collect diagnostics for Merito support now? Phoenix saves a zip on this PC and opens its folder. Nothing is sent. Yes collects the run that just failed, at once — or, when a collect you started earlier is still running, as soon as it ends: its Diagnostics Saved then says the failed run is collected next, and the zip saved after it is the one to send. No closes the dialog, and you can still collect later. A conversion you stopped with Cancel asks nothing. A failed analysis has no dialog: its status line names Collect Diagnostics… (3 below).
- The Start Menu shortcut: Start Menu > Merito > Merito Phoenix for UFT
Collect Diagnostics (type collect diagnostics in Start search). It
collects without opening the Migration Console, so it also works after you
closed the console and when the console will not start. A small window
says Collecting diagnostics for Merito support… while it works, usually
under a minute; then the console's own Diagnostics Saved message names
the zip, and its folder opens. It takes the newest run, and saves the
bundle in your profile's
out\folder, the one the Migration Console uses when started from the Start Menu. - Collect Diagnostics… in the Migration Console, or the command line below. The button sits bottom left beside Back on every step, and works even while a conversion runs, which is how a hang is collected. It takes the run in progress, else the last analysis's, says where the bundle is when it is done, and opens its folder.
From the command line, in the folder you launch Phoenix from (uft-migrate
is on PATH when setup added it, its default; otherwise use
<install folder>\bin\uft-migrate.cmd):
uft-migrate diagnostics collect
It includes the newest run, or the one you name with --run or --run-dir;
--no-run collects the logs and the environment only, and --list prints
what would be collected and writes no bundle (only the collector's own process
log). When uft-migrate itself cannot start,
"<install folder>\runtime\python.exe" -m uft_migrate.diagnostics collect
runs the same collector. Every option is in usage.md §
Collecting diagnostics.
With the dialog, the shortcut or the button, if crash dumps, or the scripts of
failed tests, exist for the run, one question asks first whether to save them
as well, to a separate file: Yes saves only what it named, No the logs
only, and Cancel nothing at all. Otherwise nothing is asked. The command
line asks nothing: its --include-… options decide (below).
When none of these works, zip the logs folder itself and send that zip: in
File Explorer, type %LOCALAPPDATA%\Merito\UFT Phoenix in the address bar,
right-click the logs folder and choose Send to > Compressed (zipped)
folder (on Windows 11, Compress to ZIP file). When that folder does not
exist, the logs are in %TEMP%\Merito UFT Phoenix\logs. The ALM password is
masked in it, as in every log record (see the table above). Unlike a bundle,
it keeps the ALM server, domain, project, user and test names and your Windows
user name, and it lacks the environment, Windows' crash reports, the run's
journal, logs and results that a bundle takes from the run folder, and
TRIAGE.md. Never send the run folder instead: it holds your test sources and
can be gigabytes.
Where it is saved. In the output folder:
out\_support\UFTPhoenix-diagnostics-<version>-<time>.zip, beside a folder of
the same name that holds the same files unzipped, so you can read every file
before you send it; MANIFEST.json lists each file with its SHA-256 hash. The
Start Menu shortcut uses the out\ folder of your profile,
%USERPROFILE%\out. When out\ does not exist or cannot be written, the
bundle goes to %LOCALAPPDATA%\Merito\UFT Phoenix\support\. Diagnostics
Saved always names the path.
Nothing is sent. Collecting opens no network connection, logs in to nothing, starts neither UFT nor the ALM client, and writes nothing into a run folder. You send the zip yourself, by your usual channel.
What is inside: the process logs of the last 30 days, as far back as
Phoenix keeps them (on a busy PC the oldest are deleted sooner, once the logs
folder passes 200 MB; when there are more than a bundle holds, the newest come
first); the environment (Windows, Python and pywin32, the UFT One and ALM
client versions, Windows Error Reporting's settings and crash reports,
Application events 1000 and 1001, and doctor's read-only checks); the run's
logs, journal and results, chosen by exact file name; and TRIAGE.md, the
first look Merito support takes, which you can read too.
What is never inside: your test scripts, data tables, object repositories or
function libraries (alm_aom_work\, converted\), the Migration Console's
settings file, .env files, license files or memory dumps. ALM server, domain,
project, user, test, folder and library names are replaced by tokens such as
project-1 and test-3f9a2c, and so is the licensee of a Merito Phoenix for UFT license
(licensee-1), with the ALM projects a license names, even inside Phoenix's
own sentences about the license; the file that maps the tokens back,
…KEEP-PRIVATE-names.json, stays beside the zip on this PC. The environment
names the edition in use by license id, limit and expiry only. --keep-names
keeps the names, the licensee's included. Phoenix's own words in its records (event and
step names, exception types, its code lines, COM member names) stay as they
are, even where one equals a name of yours: a test named Terminal does not
turn the journal's terminal records into tokens. A bundle that cannot be
cleaned is not written at all.
The ALM password. A value that follows a name such as password,
--password or UFT_MIGRATE_ALM_PASSWORD is masked in every file. Every file
is also searched for the password itself, in each of its encodings, and a file
that still holds it is left out and listed in MANIFEST.json — when the
collector knows the password. Collect Diagnostics… passes it, and the
collector also reads the password the Migration Console saved in
out\.uft-migrate-gui-cache.json (decrypted in memory, for your Windows account
only) — which is how the Start Menu shortcut, started in your profile, knows
it. From a command line, set UFT_MIGRATE_ALM_PASSWORD before
uft-migrate diagnostics collect. When no password was available,
MANIFEST.json says so under redaction.limits: no ALM password was available
to scan by value.
The separate file. Crash dumps and failed tests' scripts are saved only if
you answer Yes to the question about them, and then only the kinds it
named (or when you pass --include-dumps, --include-failed-tests or
--include-test), and only to a second file, …-EXTRAS-SENSITIVE.zip. A dump
can hold your ALM password and test data, and the scripts are your test code.
Send that file only if Merito support asks for it, by a secure channel, and
change the ALM password afterwards. Windows writes a dump only where it was set
up to: when a native crash left none, Merito support may ask your
administrator to switch crash dumps on for Phoenix for a while and make the
crash happen again, the one case where a problem must be repeated; support
sends the steps, including the one that switches dumps off again.