Documentation › Troubleshooting

Troubleshooting

The Builder checks a short list of rules and explains each failure with the line number and the reason. The line numbers are the plain-text runbook's. Fix the text, save it, and drop it on the Builder again.

The Builder refuses the file

The Builder says	Why	Fix
This file type is not supported	The file name does not end in `.txt`, `.html` or `.htm`.	Drop a plain-text runbook (`.txt`), or an interactive runbook (`.html`) to upgrade it.
This HTML file is not an interactive runbook	The `.html` file was not made by the Builder or by the earlier Runbook Viewer, so there is no runbook text in it to take out.	Drop the plain-text runbook (`.txt`) instead.
This file is not saved as UTF-8	The file is in another encoding, often ANSI from an older editor.	Save it as UTF-8. In Notepad, choose UTF-8 in the Encoding list when you save. UTF-16 with a byte-order mark also works.
This is not a text file	The file holds binary data.	Drop the plain-text runbook, not a Word document or a PDF.
The line contains `</script`, which would cut the runbook short when it is built	That sequence ends the block that holds the runbook inside the HTML.	Write it another way, such as `'</scr' + 'ipt>'`.
The line contains `<!--`, which can stop the interactive runbook from being built correctly	Same problem with the start of an HTML comment.	Write it another way, such as `'<!' + '--'`.
A runbook must start with its header	Line 1 is not exactly `<#`.	Put `<#` alone on the first line, with nothing before it, not even a blank line.
The header has no closing `#>` line	The header never ends.	Put `#>` on a line of its own after the header lines.
The first line inside the header must be the title of the runbook	Line 2 is empty or starts with `Prepared by:`, `Version:`, `Compatible with:`, `Shell:` or `Language:`.	Put the title on line 2 and the other header lines after it.
The shell must be PowerShell, pwsh, Bash, sh or zsh	The `Shell:` line says something else.	Use one of those five names, or leave the line out for PowerShell. For a database runbook use `Language: MySQL` instead.
The language must be MySQL	The `Language:` line says something else.	Use `Language: MySQL`. For a shell, use a `Shell:` line instead.
Use either Shell: or Language: in the header, not both	The header has both lines.	Keep the one the code is written for.
There is already a Section N, on line M	Two section banners use the same number.	Give each section its own number.
There is already a step N-X, on line M	Two steps in the same section use the same letter.	Give each step in a section its own letter.
There is already a Settings step, on line M	The runbook has two steps titled `Settings`.	Keep one. To load settings again in a later step, set each setting to itself on a line of its own (Section 2.8).
No steps were found	No step title and dashed line were recognized.	Each step needs a blank line above it, a title line starting `#` , and a line of three or more dashes under the title (Section 2.5).
The Settings step may only hold setting lines	A line in the Settings code is not a setting starting in the first column: `$name = value` in PowerShell and pwsh, `name=value` in Bash, sh and zsh, `SET @name = value;` in MySQL.	Move commands and worked-out values to a later step. Remove comments from the code.
`$name` is already set on line N	The same setting appears twice. PowerShell and MySQL names are compared ignoring letter case.	Keep one.
The value is a command or an expression	The value is not quoted text, a number, or true/false.	Quote the text, or set the value in a later step if the shell has to work it out.
The value contains `$` or a backtick sequence that PowerShell would expand The value contains `$` or a backtick that Bash would expand	Double-quoted text with something the shell would substitute.	Use single quotes, or put a backtick before each `$` in PowerShell, a backslash before each one in Bash, sh and zsh.
There is text after the closing quote	Something follows the value.	One value per line, nothing after it.
There is a comment after the value	A `#` comment follows the value.	Move the comment above the code, into the step's description.
The closing quote is missing	The quoted value never closes.	Add the closing quote.
No value is given	Nothing after the `=`, in PowerShell, pwsh or MySQL. (In Bash, sh and zsh, `name=` is a valid empty setting.)	Give a value, even an empty one: `""`, or `''` in MySQL.

The full list of rules is in Section 2.10.

It builds, but looks wrong

These break no rule, so the Builder does not stop, but the preview shows the problem.

What you see	Why	Fix
A step is missing, and its title appears inside the previous step's code	No blank line before the title.	Put a blank line above every step title.
Part of the description shows up in the code block	A comment line is written `#note` instead of `# note`, so it counts as code.	Start every comment with `#` and a space, or a bare `#`.
A comment is copied along with the code	It comes after the code has started.	Keep all comments above the first line of code.
Fewer steps than expected in the Builder's summary	A title or dashed line was not recognized.	Check each step against Section 2.5: blank line, title, dashes.
A section is numbered wrongly	The middle banner line does not read `SECTION N: title`.	Match the shape in Section 2.4.
`Prepared by` or `Compatible with` does not show under the title	The key is misspelt, so the line is ignored.	Check the spelling of the header keys.
A Settings field is missing	The step is not titled exactly `Settings`, or the line is not a setting.	Title the step `# Settings` and check the line against Section 2.8.
Done marks disappeared after a rebuild	The runbook text changed, however slightly, which starts the runbook's memory afresh.	Expected. Operators save a progress file if they need to keep their place, though it will not load into changed text either. Rebuilding unchanged text with a newer Builder keeps the memory.

In an interactive runbook

What you see	Why	Fix
This runbook cannot be shown	The runbook text inside the file breaks a rule. The file was changed after it was built, or built from a broken text by hand.	Send it back to the author to build again, or drop the file on the Builder: it takes the text out, lists what to correct, and offers Save plain-text runbook.
This progress belongs to title, version v, not to this runbook	The progress file was saved from a different runbook text.	Progress only loads into the runbook it was saved from, with the same text. Check the steps off by hand, using the times in the file.
The file is not a runbook progress file	Wrong file chosen, or the file was edited.	Choose the `.progress.json` file saved by the runbook.
Copy failed, select the code by hand	The browser blocked clipboard access.	Select the code with the mouse and copy it the usual way.
A step is grayed out and dashed	The step before it is not marked Done.	That is the order holding. Finish the previous step, or uncheck it if it was checked by mistake.
The settings are locked	The Settings step is marked Done.	Uncheck Done on the Settings step to change a value.
The hash does not match the one you were sent	The file was changed on the way: converted line endings, saved from an editor, or tampered with.	Do not use the file. Get a fresh copy from the author.