Sqlbootstraplog Review

SQL Server Setup Bootstrap Log Review Skill

Purpose

Analyze SQL Server Setup Bootstrap log artifacts to find why an installation, upgrade, patch (CU/SP), repair, or cluster node operation failed — and to flag risky setup-time configuration before it becomes production drift. Applies 24 checks (U1–U24) across four categories:

• U1–U6 — Summary and outcome: final result failure, exit-code extraction, failed

rules, partial feature failure, patch/upgrade per-instance failures, component update phase failures

• U7–U13 — Rule-failure patterns: pending reboot, disk space, account/permission,

prerequisites, cluster rules, policy blockers, Global Rules phase

• U14–U18 — Detail.txt and MSI forensics: end-of-file exceptions, MSI "Return value 3",

setup crashes, failure-chain root-cause ordering, Datastore state files

• U19–U24 — ConfigurationFile.ini review: service accounts, instant file

initialization, TempDB layout, security surface, feature sprawl, directory placement

Setup runs three phases — (1) Global Rules verification, (2) Component update, (3) the user-requested action — and writes a dated log folder per run. This skill is the installation-layer counterpart to sqlerrorlog-review (runtime) and sqldbconfig-review (post-install drift).

Input

Accept any of:

• Summary.txt or Summary__.txt — overall result, machine

properties, discovered features, user input settings, detailed per-feature results, rules with failures or warnings

• Detail.txt — time-ordered action execution log; errors and exceptions appear at the

end of the file

• MSI / MSP log files (__.log) — msiexec package logs
• ConfigurationFile.ini — the input settings recorded for the run (reusable for

unattended installs; passwords and PID are not saved into it)

• SystemConfigurationCheck_Report.htm content (pasted as text) — rule names, short

descriptions, and execution status

• %temp%\sqlsetup*.log — logs from unattended-mode runs
• A natural-language description ("setup failed with 0x851A001A installing the engine")

Where the files live

%programfiles%\Microsoft SQL Server\\Setup Bootstrap\Log\            \Setup Bootstrap\Log\\
    Summary__.txt
    Detail.txt
    ConfigurationFile.ini
    SystemConfigurationCheck_Report.htm
    .log                  ` matches the version being installed: 130 = SQL 2016, 140 = SQL 2017,
150 = SQL 2019, 160 = SQL 2022. All files in a log folder are archived into `Log*.cab`.
Unattended-mode logs land in `%temp%\sqlsetup*.log`.

### Pre-flight helper script

Before installing or patching, run [`scripts/check-pending-reboot.ps1`](scripts/check-pending-reboot.ps1)
to detect the pending-reboot conditions that fail Setup's "Restart computer" rule (U7) —
Component Based Servicing, Windows Update, PendingFileRenameOperations, pending computer
rename, and the ConfigMgr client signal. Exit code 0 = clear, 1 = reboot pending. See
[`scripts/README.md`](scripts/README.md) for usage.

## How to Run

1. **Identify the artifact type(s)** in the input: Summary, Detail, MSI log, INI, rules
   report, or a mix.
2. **Parse the Summary first** when present — `Final result:`, `Exit code (Decimal):`,
   `Requested action:`, `Detailed results:` (per-feature `Status:` / `Component error code:` /
   `Error description:`), and `Rules with failures or warnings:`.
3. **Run U1–U13** against the Summary/rules content.
4. **Run U14–U18** against Detail.txt and MSI logs when provided — search Detail.txt from
   the end for "error" / "exception"; search MSI logs for "value 3".
5. **Run U19–U24** against ConfigurationFile.ini or the `User Input Settings:` section of
   the Summary (the same parameters appear in both).
6. **Order findings by causality** — the first failing action or rule is the root cause;
   later failures are usually cascade (U17).
7. If a check cannot be evaluated because its artifact is absent, report
   "Cannot evaluate —  not provided" rather than skipping silently.

---

## Summary and Outcome Checks (U1–U6)

### U1 — Setup Final Result Failed
- **Trigger:** Summary contains `Final result:` with `Failed`, `Cancelled`, or
  `Setup completed with required actions` (anything other than `Passed`)
- **Severity:** Critical
- **Fix:** Extract `Exit code (Decimal):`, `Requested action:`, and every feature in
  `Detailed results:` whose `Status:` is not `Passed`. Report the `Error description:` and
  `Component error code:` for each failed feature, then continue with U2–U18 to find the
  root cause. The `Next step for :` lines state Microsoft's recommended recovery
  order (resolve, uninstall the feature, rerun setup).

### U2 — Component Error Code Extraction
- **Trigger:** `Component error code:` present in `Detailed results:` (commonly a
  `0x84xxxxxx` or `0x85xxxxxx` setup facility code) or a negative `Exit code (Decimal):`
- **Severity:** Critical when paired with a failed feature; Info when historical
- **Fix:** Report the hex code, the paired `Error description:`, and the
  `Error help link:` URL (it encodes product version and event ID for Microsoft's
  troubleshooting lookup). Well-known example: `0x851A001A` — "Wait on the Database Engine
  recovery handle failed" — means the engine did not start during configuration; the real
  cause is in the new instance's ERRORLOG (`MSSQL.\MSSQL\LOG\ERRORLOG`) —
  hand off to `/sqlerrorlog-review`.

### U3 — Failed Setup Rules Listed
- **Trigger:** `Rules with failures or warnings:` section lists any rule with `Failed`
  status (rule warnings alone are Info)
- **Severity:** Critical for failed rules; Info for warnings (e.g., `IsFirewallEnabled`)
- **Fix:** Name each failed rule and apply the matching pattern check (U7–U13). The
  `Rules report file:` line points at `SystemConfigurationCheck_Report.htm`, which holds a
  short description for every executed rule and its status — request it if the rule name
  alone is ambiguous.

### U4 — Partial Feature Failure
- **Trigger:** `Detailed results:` shows at least one feature `Failed` while another
  feature `Passed` in the same run
- **Severity:** Critical
- **Fix:** The machine now has a partial install. Features whose
  `Reason for failure:` says "an error occurred for a dependency of the feature" failed as
  cascade — fix the root feature first (typically Database Engine Services). Follow the
  `Next Step:` guidance per feature: resolve, uninstall the failed feature, rerun setup.
  Validate post-repair with `/sqlerrorlog-review` on first startup.

### U5 — Patch/Upgrade Per-Instance Failure
- **Trigger:** `Requested action:` is `Patch`, `Upgrade`, or `RemovePatch` AND the log
  folder contains per-instance subfolders (e.g., `...\\MSSQLSERVER\`) with
  at least one instance summary reporting failure while others passed
- **Severity:** Critical
- **Fix:** When patching, setup writes one subfolder per patched instance plus one for
  shared features, each with its own summary/detail set. A failed instance leaves the
  server with mixed binary versions — re-run the patch for the failed instance before the
  next maintenance window closes. Compare `@@VERSION` per instance to confirm.

### U6 — Component Update Phase Failure
- **Trigger:** Failure during phase 2 (component/product update): Summary's
  `Product Update Status:` reports an error, or Detail.txt shows the media-update step
  failing (download blocked, WSUS/Microsoft Update unreachable)
- **Severity:** Warning
- **Fix:** The update search runs before the main action and fails on offline or
  proxy-restricted servers. Re-run with `/UpdateEnabled=False` (or `UpdateEnabled=False`
  in the INI) to skip the online check, or point `UpdateSource` at a local folder holding
  the downloaded CU. Patch to the target build immediately after install.

---

## Rule-Failure Pattern Checks (U7–U13)

### U7 — Restart Computer Rule Failed (Pending Reboot)
- **Trigger:** Failed rule indicating a required restart (e.g., `RebootRequiredCheck` /
  "Restart computer" rule) in the Summary rules section or the rules report
- **Severity:** Critical (blocks setup until cleared)
- **Fix:** Windows has a pending reboot — most commonly `PendingFileRenameOperations`
  under `HKLM\SYSTEM\CurrentControlSet\Control\Session Manager`. Reboot, then rerun
  setup. Diagnose all five signals (CBS, Windows Update, pending file renames, pending
  computer rename, ConfigMgr) with this skill's
  [`scripts/check-pending-reboot.ps1`](scripts/check-pending-reboot.ps1) — run it with
  `-ShowDetail` to see which files are waiting and which product left the state behind.
  If the state returns after every reboot, an agent/AV product is re-creating it; clear
  that product before the maintenance window.

### U8 — Disk Space Rule Failed
- **Trigger:** Failed rule or error text indicating insufficient free space on a target
  drive (install drive, system drive, or data/log directories)
- **Severity:** Critical
- **Fix:** Free or extend the named volume. Remember setup also needs temp working space
  and the `Setup Bootstrap\Log` folder grows per run. If the failure names a data/log
  directory from the INI, repoint `INSTALLSQLDATADIR` / `SQLUSERDBDIR` / `SQLUSERDBLOGDIR`
  to a volume with capacity (see U24).

### U9 — Account or Permission Rule Failed
- **Trigger:** Failed rule or error text concerning service account validation, the
  installing user's rights (not local admin, cannot validate credentials), or a domain
  account lookup failure (wrong password, locked account, unreachable DC)
- **Severity:** Critical
- **Fix:** Re-enter service account credentials; confirm the account is not locked or
  expired; run setup elevated from an account with local Administrators membership. For
  gMSA accounts, confirm the host has rights to retrieve the managed password. For
  cluster/AG node additions, the installing account also needs rights on the cluster
  object. Hand off to `/sqlspn-review` if Kerberos/SPN errors follow first startup.

### U10 — Prerequisite Rule Failed
- **Trigger:** Failed rule for a missing prerequisite — .NET Framework, PowerShell,
  OS version/edition not supported by the SQL Server version being installed
- **Severity:** Critical
- **Fix:** Install the named prerequisite and rerun. For OS-version failures there is no
  workaround — use a SQL Server version supported on that OS, or move to a supported OS.
  Check the target version's "hardware and software requirements" page on MS Learn for
  the exact prerequisite matrix.

### U11 — Cluster Rule Failed
- **Trigger:** Failed rule in a failover-cluster or AddNode/RemoveNode scenario —
  cluster service validation, shared-disk checks, node membership, or cluster security
  policy rules
- **Severity:** Critical
- **Fix:** Run the WSFC Cluster Validation wizard first and fix its findings; setup's
  cluster rules are a subset. Confirm the installing account has cluster management
  rights and that all nodes run the same OS patch level. Pair with
  `/sqlclusterlog-review` when the cluster log shows resource failures around the same
  timestamp.

### U12 — Security Policy Blocker
- **Trigger:** Error text indicating the package or media was blocked: Group Policy
  software restriction / AppLocker denial, unsigned or blocked MSI, media copied with a
  zone identifier (mark-of-the-web), or AV quarantining setup binaries
- **Severity:** Critical
- **Fix:** Unblock the media (file Properties → Unblock, or copy via a method that strips
  the zone identifier), add a temporary AppLocker/SRP exception for the setup folder, and
  exclude the setup working directories from real-time AV scanning for the duration of
  the maintenance window.

### U13 — Global Rules Phase Failure
- **Trigger:** Setup terminates during phase 1 (Global Rules verification) before
  reaching feature selection — Summary shows only global rule results and no
  `Detailed results:` per-feature section
- **Severity:** Critical
- **Fix:** The environment fails basic requirements (unsupported OS, missing elevation,
  pending reboot, broken WMI). Fix the named global rule (apply U7–U12 patterns).
  If rules cannot even execute, verify WMI health and rerun from an elevated prompt.

---

## Detail.txt and MSI Forensic Checks (U14–U18)

### U14 — Exception at End of Detail.txt
- **Trigger:** The final portion of Detail.txt contains an error or exception block
  (search the end of the file first, then keyword-search "error" / "exception" — the
  documented diagnostic method for this file)
- **Severity:** Critical
- **Fix:** Detail.txt is written in action-invocation order, so the exception at the end
  is the action that stopped the run. Report the failing action name, the exception type,
  the inner exception (when present — it usually carries the OS error), and the
  timestamps. Map the action back to the feature reported in U1.

### U15 — MSI Return Value 3
- **Trigger:** An MSI log contains `Return value 3` (the documented failure marker —
  search "value 3" and read the lines immediately before it)
- **Severity:** Critical
- **Fix:** The custom action or install step immediately preceding `Return value 3` is the
  failure point; the surrounding lines carry the real Windows Installer error (1603,
  1935, 1607, ...). Report the failing action, the MSI error code, and the package name
  from the log file name (`__.log`). Generic 1603
  with no obvious cause: check U12 (policy blockers) and Windows Installer service health.

### U16 — Setup Process Crash
- **Trigger:** Detail.txt or Summary indicates the setup process itself terminated
  abnormally (Watson bucket reference, "SQL Server Setup has encountered an error", an
  abrupt end of Detail.txt with no closing summary)
- **Severity:** Critical
- **Fix:** Distinguish "setup ran and an action failed" (U14/U15) from "setup crashed".
  For crashes: rule out corrupt media (re-download, compare checksums), run from a local
  path instead of a network share, and check the Application event log for the crashing
  module. A Detail.txt that simply stops mid-action with a `Final result` of `Pending`
  often means the process was killed or the host restarted mid-run.

### U17 — Failure Cascade Ordering
- **Trigger:** Multiple features or actions report failure in one run
- **Severity:** Info (analysis ordering check — always apply when U1/U4 fire)
- **Fix:** Order all failures by timestamp from Detail.txt and by dependency from
  `Reason for failure:` text. Report exactly one root cause (the earliest independent
  failure); list the rest as cascade. Fixing the root cause and rerunning usually clears
  every dependent failure — do not chase dependency failures individually.

### U18 — Datastore State Referenced
- **Trigger:** Summary/Detail are inconclusive (e.g., configuration values look wrong but
  no action failed) AND the Datastore folder is available
- **Severity:** Info
- **Fix:** The `Datastore\` subfolder holds XML dumps of every configuration object per
  execution phase — a snapshot of what setup *believed* each setting to be. Ask for the
  relevant XML (instance settings, feature selections) and compare against the intended
  configuration. Useful for proving an INI/UI value was not what the operator expected.

---

## ConfigurationFile.ini Review Checks (U19–U24)

These run on `ConfigurationFile.ini` or the `User Input Settings:` section of the
Summary. Passwords, PID, and some parameters are not persisted to the INI — absence of a
password parameter is normal, not a finding.

### U19 — Service Account Choice
- **Trigger:** `SQLSVCACCOUNT` (or `AGTSVCACCOUNT`) is a shared built-in account
  (`NT AUTHORITY\SYSTEM`, `NT AUTHORITY\NETWORK SERVICE`) on a production multi-service
  install, or a regular domain user account where a gMSA/MSA was available
- **Severity:** Warning
- **Fix:** Prefer per-service virtual accounts (`NT Service\MSSQLSERVER` — the default)
  for standalone boxes, or gMSA for domain estates needing cross-machine identity (AG,
  Kerberos). Avoid

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [vanterx](https://github.com/vanterx)
- **Source:** [vanterx/mssql-performance-skills](https://github.com/vanterx/mssql-performance-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.