Fixing TIA Portal 'More Than One Starter File' V15.1 to V17 Error

1. Problem Overview

When migrating a SIMATIC project from TIA Portal V15.1 to TIA Portal V17, the engineering framework rejects the source archive during the upgrade process and emits the dialog:

"<file path> contains more than one starter file"

The error is produced by the TIA Portal Project Wizard / Open Project sequence when the migration subsystem detects more than one valid project starter container inside a single folder. A "starter file" in this context is the root .ap<version>_<hotfix> archive that TIA Portal uses to bootstrap a project (e.g. MyProject.ap15_1, MyProject.ap17). TIA Portal V17 will not perform a forward upgrade if it cannot unambiguously identify a single source project inside the target directory.

This condition is environmental rather than a defect in the project source code: the .ap15_1 archive itself is intact, but the surrounding folder state violates the migration pre-condition of "exactly one starter file".

2. Root Cause Analysis

The dominant root cause for this error is the presence of a duplicate ap15_1 starter file with the Hidden NTFS attribute set. Windows File Explorer, by default, does not display files with the Hidden attribute, so users see only one starter file and assume the project is in a valid state. The TIA Portal migration engine, however, enumerates the directory using lower-level Win32 calls that do return hidden entries, causing it to find two candidates and abort the upgrade.

Common sources of the duplicate hidden file include:

• Cloud sync clients (OneDrive, Dropbox, Google Drive, SharePoint) that create offline copies with the .tmp or ~$ prefix and may mark them hidden after conflict resolution.
• Antivirus quarantine / shadow copies that leave behind a renamed twin of the original .ap15_1 file with the Hidden attribute.
• Backup utilities (Windows File History, VSS snapshots, third-party backup) that place a copy in the same directory.
• Manual copies created by a user who then right-clicked the duplicate and selected Properties → Hidden.
• Source-control sync (SVN, Git LFS, TIA Portal Teamcenter gateway) leaving a partially synced second file.
• Malware that duplicates project files and marks one as hidden to evade casual inspection.

3. TIA Portal Starter File Format Reference

A TIA Portal project is stored as a compound archive. The starter file extension encodes the major.minor version that originally wrote the project:

Internally, an .ap15_1 file is a ZIP container that holds the project's ProjectTree, SystemData, IM (identification/maintenance), CrossRef (cross-reference), and Gra (graphics) subtrees together with a Project.bin master index. TIA Portal V17 reads this container and then performs a one-way upgrade to ap17; the upgrade is not transactional, so a clean source is mandatory.

4. Prerequisites for the Recovery Procedure

1. An installation of TIA Portal V17 (or later) with a valid license key and matching firmware support packages (F-CPU, HMI, drives) installed.
2. The original .ap15_1 file from a known-good backup, project server, or source-control repository. Do not attempt recovery on the only remaining copy.
3. Local administrator rights on the engineering workstation (required to toggle the Hidden attribute and to edit the Folder Options policy).
4. Approximately 3× the project size in free disk space to hold original, working, and upgraded copies.
5. Temporarily disabled cloud-sync and antivirus real-time scanning on the project directory to prevent re-introduction of the hidden duplicate.

5. Step-by-Step Resolution

Step 1 — Reproduce the error in a safe copy

Copy the entire project folder to a working location such as C:\Temp\Migration\MyProject. Never modify the source folder. Re-run the V17 open / migration to confirm the dialog reproduces against the copy.

Step 2 — Enable display of hidden and system files

The single most effective mitigation is to override the Windows default that hides files with the Hidden or System attribute.

1. Open File Explorer and navigate to the project folder.
2. Select View → Show → Hidden items. In older Windows builds, use Folder Options → View → Advanced settings → Files and Folders → Hidden files and folders → Show hidden files, folders, and drives.
3. Clear the checkbox Hide protected operating system files (Recommended). Accept the administrative confirmation.
4. Click Apply to Folders to make the change persistent for all sub-folders in the user profile.

Step 3 — Enumerate the starter files

After enabling hidden files, the project folder will typically reveal two .ap15_1 entries. The visible one is the original; the hidden one is usually a near-duplicate of similar size, sometimes prefixed with ~$ or suffixed with (1), (2), or .bak:

Directory: C:\Projects\MyPlant\Line1

Mode      LastWriteTime       Length  Name
-----     -------------       ------  ----
-a---     2024-03-04 09:12   18,432 KB  Line1.ap15_1
-a-h-     2024-03-04 09:14   18,432 KB  Line1.ap15_1.bak
-a-h-     2023-12-21 14:07       512 KB  Line1.ap15_1

The -a-h- mode flag confirms the Hidden attribute (h).

Step 4 — Identify the correct starter file

Compare the candidates:

• Last-write timestamp — the most recent valid write should be the live project.
• Size — significantly smaller files are typically empty or aborted sync fragments.
• Hash — compute SHA-256 with Get-FileHash -Algorithm SHA256 and cross-check against your source-control repo or a known-good backup.
• Internal integrity — every .apXX file is a valid ZIP. Run Expand-Archive -Path File.ap15_1 -DestinationPath .\probe -Force on a copy. A valid starter file will decompress cleanly and contain Project.bin and a SystemData subtree.

Step 5 — Quarantine the duplicate

Do not simply delete the hidden file in the working copy. Rename the suspect file to a neutral extension so that TIA Portal ignores it but the file is recoverable if the wrong one was chosen:

ren "Line1.ap15_1.bak"   "Line1.ap15_1.bak.IGNORE-2024-03-04"
ren "Line1.ap15_1 (1)"  "Line1.ap15_1 (1).IGNORE-2024-03-04"

Alternatively, in PowerShell:

Get-ChildItem -Path . -Filter *.ap15_1 -Hidden | ForEach-Object {
    $new = $_.BaseName + ".IGNORE-" + (Get-Date -Format yyyyMMdd) + $_.Extension
    Rename-Item -Path $_.FullName -NewName $new
}

Step 6 — Validate the working directory

Confirm that exactly one starter file matching the source version remains:

Get-ChildItem -Path . -Filter *.ap15_1 -Recurse -Force | Select-Object FullName,Length,LastWriteTime,Attributes

Expected output: a single row, no Hidden attribute set.

Step 7 — Open and upgrade in TIA Portal V17

1. Launch TIA Portal V17 with elevated rights if your installation is UAC-managed.
2. Open Project → Open and select the cleaned .ap15_1 file.
3. When prompted Do you want to upgrade the project to the current version?, click Upgrade.
4. Wait for the migration log to complete. V17 writes a new .ap17 file next to the source.
5. Perform a full project consistency check (Project → Compile → All) before any online operation.

6. Verification Procedure

7. Alternate Recovery Methods

If the hidden duplicate is the only intact copy, three fallback strategies are available:

1. Recovery from project server / source control — restore the canonical .ap15_1 from Teamcenter, SVN, or a versioned backup. The hidden file is the rogue element in this case.
2. Repair with TIA Portal "Recover" — some TIA Portal versions expose a recovery mode invoked by holding Ctrl + Shift while opening a project. This rebuilds the project index from the Project.bin subtree of the archive.
3. Manual ZIP repair — if neither copy is intact, copy the archive aside, run Repair-ZipFile -path <file> (or 7-Zip's Test function), then attempt migration of the repaired file.

8. Prevention Best Practices

• Store TIA Portal projects in dedicated, non-synced directories. Exclude the engineering root from OneDrive, Dropbox, SharePoint, and any real-time sync client.
• Whitelist TIA Portal folders in your antivirus to prevent backup-style quarantine copies from being created with the Hidden attribute.
• Apply the "Show hidden files" group policy on engineering workstations, or deploy a startup script that toggles the relevant registry value. Siemens engineering best-practice images typically include this setting.
• Use a single project root per plant area, with a project server (Teamcenter, TIA Portal Project Server) as the only authoritative location.
• Validate every project archive before long-term storage by performing a Project → Archive → Retrieve round-trip in a sandboxed V17 install.
• Adopt forward-only version policy: keep one engineering workstation at the highest installed version and let lower versions read-only; never allow two versions to write to the same directory.

9. Related Migration Issues

Migration errors that share the same root-cause family ("ambiguous project root") include:

10. Diagnostic Flowchart

11. Program-Level Error Handling in Migrated Projects

After successful migration, plant code that propagates runtime errors should be reviewed. In S7-1200/S7-1500 user programs, the GET_ERROR and GET_ERROR_ID instructions are commonly used to forward error information from a called block back to the calling block. These instructions were extended in V15.1 with the local-instance variant and have been retained unchanged in V17, but compiled instances of blocks that use them in the source project should be recompiled in V17 to refresh the system block references. Failure to recompile can leave stale type pointers that surface as "Block type could not be loaded" warnings during the first online download to a real CPU.

Recommended post-migration hardening:

1. Project-wide Compile → All (rebuild) to regenerate all type pointers and instance DBs.
2. Download the rebuilt project to a single test PLC; verify the GET_ERROR outputs reflect the new error struct format (ERROR = TRUE → ERROR_ID populated with the new DW#16#… encoding).
3. Validate that error OBs (OB82, OB83, OB86, OB121, OB122) still exist and are not empty; V15.1 → V17 migration preserves their skeletons but does not add new fault-OB variables introduced in V16/V17.

12. Field-Proven Caveats

• Project folders restored from OneDrive Version History frequently re-introduce the hidden duplicate. If OneDrive is the only recovery path, download the entire folder via the OneDrive web client (not the desktop sync) to a local directory outside the sync root.
• Some EDR (Endpoint Detection & Response) products inject a hidden marker file alongside any executable; while an .ap15_1 is not technically executable, certain heuristics still trigger a copy. Add the TIA Portal project path to the EDR exclusion list.
• Do not open the .ap15_1 archive in 7-Zip or WinRAR and then re-save it. The internal compression parameters and central directory layout used by TIA Portal are sensitive; even a valid ZIP round-trip can cause TIA Portal to reject the archive with a different error class ("file format is invalid") that is harder to recover from.
• If the engineering workstation is part of a domain with Folder Redirection enabled, the user's Documents folder may be transparently re-mounted to a network share. The TIA Portal migration engine writes large temporary files during upgrade; if the share link drops, the upgrade can leave a partial .ap17 and a hidden leftover from the previous run. Always migrate on a fully local, NTFS-formatted drive.

13. Frequently Asked Questions