sqlbootstraplog-review git:20260611.bd7f3cfA

Immutable. This exact content is served forever at /api/v1/blob/0447333c5cf29b0f.

---
name: sqlbootstraplog-review
description: Analyze SQL Server Setup Bootstrap log files to diagnose failed installations, failed Cumulative Update or Service Pack patching, failed cluster node operations, and risky setup-time configuration. Parses Summary.txt, Detail.txt, MSI/MSP logs, ConfigurationFile.ini, and SystemConfigurationCheck_Report content from the Setup Bootstrap Log folder. Applies 24 checks (U1–U24) covering final-result failure and exit-code extraction, failed setup rules (pending reboot, disk space, account permissions, prerequisites, cluster rules), Detail.txt exception forensics, MSI "Return value 3" patterns, and ConfigurationFile.ini review (service accounts, instant file initialization, TempDB layout, mixed authentication, feature sprawl, directory placement). Use this skill whenever SQL Server setup, an in-place upgrade, a patch, or add/remove node fails, or when a user pastes Summary.txt, Detail.txt, or ConfigurationFile.ini content.
triggers:
  - /sqlbootstraplog-review
  - /bootstrap-log
  - /setup-log
---

# 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_<MachineName>_<yyyyMMdd_HHmmss>.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** (`<Feature>_<Architecture>_<Interaction>.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\<nnn>\Setup Bootstrap\Log\            <- Summary.txt
%programfiles%\Microsoft SQL Server\<nnn>\Setup Bootstrap\Log\<yyyyMMdd_HHmmss>\
    Summary_<MachineName>_<yyyyMMdd_HHmmss>.txt
    Detail.txt
    ConfigurationFile.ini
    SystemConfigurationCheck_Report.htm
    <Name>.log                  <- MSI/MSP logs
    Datastore\                  <- XML state snapshots per execution phase
    MSSQLSERVER\ ...            <- per-instance subfolders when patching
```

`<nnn>` 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 — <artifact> 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 <feature>:` 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<nn>.<INSTANCE>\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., `...\<yyyyMMdd_HHmmss>\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 (`<Feature>_<Architecture>_<Interaction>.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 LocalSystem for the engine. Changing later is done via SQL Server
  Configuration Manager (it re-grants the required rights) — not Services.msc.

### U20 — Instant File Initialization Not Granted at Setup — SQL 2016+
- **Trigger:** `SQLSVCINSTANTFILEINIT` is `false` or absent in the INI / User Input
  Settings — SQL 2016+ (the parameter grants "Perform volume maintenance tasks" to the
  engine account during setup)
- **Severity:** Warning
- **Fix:** Without IFI every data-file create/grow/restore zero-fills, which multiplies
  restore and autogrow time. Grant now: add the engine service account to "Perform
  volume maintenance tasks" (secpol.msc) and restart, or reinstall pattern for fleets:
  `/SQLSVCINSTANTFILEINIT="True"` in the INI. Verify with
  `sys.dm_server_services.instant_file_initialization_enabled` (cross-check
  `/sqldbconfig-review` B22). Log files do not use IFI (except SQL 2022+ log growths
  up to 64 MB).

### U21 — TempDB Setup Parameters Undersized — SQL 2016+
- **Trigger:** `SQLTEMPDBFILECOUNT` < MIN(logical processors, 8), or
  `SQLTEMPDBFILESIZE` left at the 8 MB default for a production engine —
  SQL 2016+ (setup-time TempDB parameters)
- **Severity:** Warning
- **Fix:** Setup defaults are sized for tiny machines. Set
  `SQLTEMPDBFILECOUNT` = MIN(logical processors, 8), equal `SQLTEMPDBFILESIZE` for all
  files (hundreds of MB to GBs for busy OLTP), matching `SQLTEMPDBFILEGROWTH`, and a
  dedicated volume via `SQLTEMPDBDIR` (see U24). Already installed? Fix live and
  validate with `/sqldbconfig-review` B23 and `/sqldiskio-review` Z7–Z9.

### U22 — Security Surface Widened at Setup
- **Trigger:** `SECURITYMODE=SQL` (mixed authentication) without a stated requirement;
  `TCPENABLED=0` on a server meant to accept remote connections (or `1` on a local-only
  box); `NPENABLED=1` (named pipes) without a legacy client need
- **Severity:** Warning
- **Fix:** Mixed mode adds the `sa` attack surface — prefer Windows authentication and
  enable mixed mode only for documented application needs (then rename/disable `sa`).
  Align protocol flags with intent; change later in SQL Server Configuration Manager
  (TCP/NP per instance). Cross-check post-install posture with `/sqldbconfig-review`
  B24–B28.

### U23 — Feature Sprawl in FEATURES List
- **Trigger:** `FEATURES` installs components beyond the stated purpose of the server
  (e.g., `AS`, `RS`, `DQ`, `IS` on an engine-only OLTP box)
- **Severity:** Info
- **Fix:** Every installed feature is patch surface, attack surface, and memory
  competition (AS/RS run their own services outside `max server memory`). Uninstall
  unused features via Programs and Features → SQL Server → Remove, or keep the INI's
  `FEATURES=SQLENGINE[,REPLICATION]` minimal for the next build.

### U24 — Directory Co-location at Setup
- **Trigger:** `INSTALLSQLDATADIR`, `SQLUSERDBDIR`, `SQLUSERDBLOGDIR`, `SQLTEMPDBDIR`,
  and `SQLBACKUPDIR` resolve to the same volume, or any of them sit on the system drive
  (defaults under `C:\Program Files\Microsoft SQL Server\` count)
- **Severity:** Warning
- **Fix:** Separate at install time — it is far cheaper than moving files later: data,
  log, TempDB, and backups each on appropriate volumes; nothing growing on the system
  drive. The INI parameters map 1:1 to the Database Engine Configuration → Data
  Directories setup page. Post-install validation: `/sqldiskio-review` Z6–Z10.

---

## Version-Aware Check Suppression

If the SQL Server version is stated by the user or visible in the Summary (`Version:`
under Package properties), read `VERSION_COMPATIBILITY.md`
(`~/.claude/skills/VERSION_COMPATIBILITY.md` if installed, or
`skills/VERSION_COMPATIBILITY.md` from the repo). If unavailable, skip silently. For
checks whose minimum version exceeds the instance version: verbose mode → log as
`SKIP (version: requires SQL 20XX+, instance is SQL 20YY)`; standard report → omit
entirely. Do not suppress `NOT ASSESSED` rows from missing input — only suppress
version-inapplicable checks. This skill applies to SQL Server on Windows only — the
Setup Bootstrap log layout does not exist on SQL Server on Linux, Azure SQL Database, or
Azure SQL Managed Instance.

---

## Output Format

Present findings in this order:

1. **Setup Outcome Summary** — one sentence: action attempted, final result, root cause.
2. **Run facts table** — version/edition, requested action, start/end time, exit code,
   log folder timestamp.
3. **Findings table** — one row per triggered check:

| Check | Severity | Artifact | Finding | Fix |
|-------|----------|----------|---------|-----|
| U1 | Critical | Summary.txt | Final result Failed, exit 0x851A001A on SQLEngine | Check new instance ERRORLOG; see U2 |

4. **Root cause** — single root cause (per U17 ordering) with the failing action/rule
   and evidence lines quoted.
5. **Recovery sequence** — ordered, concrete steps (resolve → uninstall failed feature
   if required → rerun → post-install validation), with companion skill references.
6. **Configuration advisories** — U19–U24 findings, separated from the failure analysis.

> Analyzed by: `sqlbootstraplog-review` (U1–U24)

---

## Companion Skills

- `/sqlerrorlog-review` — the engine ERRORLOG explains "Wait on the Database Engine
  recovery handle failed" (0x851A001A) and any post-install startup failure; run it on
  the new instance's first ERRORLOG
- `/sqldbconfig-review` — validates the running instance against the configuration the
  INI promised (IFI B22, TempDB B23, surface area B24–B28)
- `/sqlclusterlog-review` — when cluster rules fail (U11) or an AddNode operation breaks
  mid-flight, the WSFC cluster log shows the cluster-side view
- `/sqldiskio-review` — post-install validation of the directory/volume choices reviewed
  by U24
- `/sqlspn-review` — service account changes at setup (U19) often surface later as SPN
  registration failures

---

## VERSION_COMPATIBILITY

See [skills/VERSION_COMPATIBILITY.md](../VERSION_COMPATIBILITY.md) for the full compatibility matrix.

| Check | 2008 R2 | 2012 | 2014 | 2016 | 2017 | 2019 | 2022 | Azure SQL |
|-------|---------|------|------|------|------|------|------|-----------|
| U1–U18 (log analysis) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | N/A |
| U19 Service accounts | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | N/A |
| U20 IFI at setup | — | — | — | ✓ | ✓ | ✓ | ✓ | N/A |
| U21 TempDB at setup | — | — | — | ✓ | ✓ | ✓ | ✓ | N/A |
| U22–U24 (INI review) | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | N/A |

Azure SQL Database and Azure SQL Managed Instance have no user-visible SQL Server Setup;
this skill is for SQL Server on Windows.