ottr_troubleshooting.knit

OTTR Troubleshooting
Common Errors

Last updated: September 11, 2026

Use this checklist when an OTTR course, website, or pull request preview does not render as expected.

Content Is Not Rendering or Updating

Confirm the repository GH_PAT secret is current.
If the action shows exit code 128, update the token using the Update Token/Secret cheatsheet.
Compare your config_automation.yml with the template version in OTTR_Template.
Keep your custom configuration choices, but update outdated settings.
Check whether workflow files are out of date.
Request sync updates using the OTTR Sync cheatsheet.
Push a small change, such as a blank-space edit, to re-run the workflow.
Check GitHub Status if actions do not start or fail before running your code. If there appears to be an issue, you may need to wait a bit until they are resolved and make a new arbitrary change.

Google Slide Image Is Not Showing

Check the ottrpal::include_slide() code chunk.
- Confirm the fig.alt argument has no line breaks.
- Use one quotation style around the full fig.alt value.
- Avoid mixing quote styles in a way that closes the string early.
- Confirm the Google Slides file is shared with Anyone with a link can view.

# Good: double quotes outside, single quotes inside
fig.alt = "This slide highlights 'one phrase' in the image."

# Good: single quotes outside, double quotes inside
fig.alt = 'This slide highlights "one phrase" in the image.'

Pull Request Render Fail

When the rendering check fails:

Click Details beside the failed check.
Find the named step that failed.
Match the error message below.
Fix the source file on your branch.
Commit the fix and wait for checks to run again.

file is not in PNG format

This often means ottrpal::include_slide() could not retrieve a public image from Google Slides.

Open the Google Slides presentation.
Set sharing to Anyone with a link.
Re-check the slide URL in the code chunk.
Commit a small change to re-run the render.

Process completed with exit code 1

This can be expected when spell check, URL check, or quiz format check finds problems.

Return to the pull request page.
Find the automated comment for spelling, URL, or quiz errors.
Click Download the errors here.
Fix each listed file.
Commit the fixes to re-run the checks.

CONFLICT (modify/delete)

This can happen when the preview branch has stale rendered changes.

Note your pull request number.
Go to Code > Branches in GitHub.
Find the branch named preview-<pull request number>.
Delete that preview branch.
Re-trigger the GitHub Actions run.

Parser error: while parsing a flow sequence

This usually means _bookdown.yml has a missing comma, quote, or bracket.

Open _bookdown.yml.
Check that every file name is quoted.
Check that every file except the last one has a comma.
Check that the closing ] is present.
Commit the corrected YAML.

rmd_files: ["index.Rmd",
            "01-intro.Rmd",
            "02-chapter_of_course.Rmd",
            "new_file.Rmd",
            "About.Rmd",
            "References.Rmd"]

Word preview download link gives a 404 error

Open _output.yml.
Add the Word output format below if it is missing.
Commit the change and re-run the preview action.

bookdown::word_document2:
  toc: true

the condition has length > 1

This can happen when GA_Script.Rhtml includes extra HTML document wrappers.

Open GA_Script.Rhtml.
Remove opening <html>, <head>, <title>, and <body> tags if they are present.
Remove closing </body> and </html> tags if they are present.
Commit the cleaned file.

Authors: Padmashri Saravanan from BioData Sage created the cheatsheet content. Carrie Wright reviewed the material. Kate Isaac created the original styling, Carrie Wright did the css styling and Carrie Wright and Candace Savonen did the publishing engineering for the cheatsheet. OTTR was created and or is maintained by the following team: Candace Savonen, Carrie Wright, Kate Isaac, Ava Hoffman, Adam Coffman, Katherine Cox, Federick Tan, John Muschelli, Howard Baek, and Jeffrey Leek.