Troubleshooting handbook edits

Start with the symptom below. For help, share the page or failed job URL in #handbook or #mr-buddies. Keep internal content in channels approved for that information.

404 errors with edit action

When clicking on Edit this page in the upper right corner on a handbook page in your browser, you might get a 404 error in the GitLab Web IDE.

As a team member, this problem can be related to an expired SAML SSO session for your GitLab.com profile and Okta. In order to mitigate and solve the problem, click on View page source to trigger the SAML authentication with Okta again.

Alternatively, navigate into our GitLab.com profile into your To-Do list, or try to open a confidential issue, to trigger the authentication.

It can also be browser related: Try clearing the cache, open an incognito window (on macOS: cmd shift n), or use a different browser to test.

404 error on new page

If a new page is created as part of a merge request, but the page is not showing up on the site, check the file name.

The most common issue is using index.md instead of _index.md in a folder that has other pages. The other pages will not display.

See pages and folder structure for more information.

Images not loading properly

If you added new images and they are not loading properly in your review app, please review the Images section of the markdown guide.

Failing pipelines

You can give an agent the failed job URL or paste the relevant lint output. Ask it to explain the cause, reproduce the check locally, and fix only the reported issue. Local checks can cover different files from CI, especially after committing; ask which files and baseline were tested. An infrastructure failure is not a lint error.

Use one of the following agents for help:

1. For focussed CI/CD help: Fix CI/CD Pipeline Flow, CI Expert agent
2. For general help: Developer Flow and Agentic Chat
3. Local agents: GitLab Duo CLI, Claude Code, or any other approved AI tool, together with the GitLab MCP server.

To see why your pipeline is failing, there are two main places to look:

1. The latest comment by the bot on your merge request. It should have a list of all linter errors. However, build errors do not generate a comment.
2. Individual failed jobs. On the MR > “Pipelines” tab > select any red circle > select a failed job. Error messages are near the bottom of the job log and start with Error.

In the job log, error messages typically provide you:

1. the error
2. the file where the error occurred
3. the line number
4. the character number (where on the line it is)

For example:

Error: error building site: assemble: "/builds/gitlab-com/content-sites/handbook/content/handbook/security/security-assurance/field-security/trust_center_guide.md:1:2": closing tag for shortcode 'details' does not match start tag`

- File: `content/handbook/security/security-assurance/field-security/trust_center_guide.md`
- Line: 1
- Character: 2

To fix markdown errors, review the message. Alternatively, review the relevant section in the markdown style guide.

For build or setup errors, see the development troubleshooting guide. If the cause is unclear, include the failed job URL when asking for help.

See the following sections for specific errors.

If the problem was on the main branch, you may need to rebase.

If you’re unsure, you can reach out for help.

Link and anchor errors

There is a linter (Hugolint) that validates links and anchors across the handbook. If your change introduces new broken links, then the pipeline job will fail. Follow the instructions in the previous failing pipelines section for how to find the list of errors.

There are two main reasons it will fail:

1. Content added in the MR includes a broken link.
2. Content changed in the MR breaks an existing link.

Here’s an example of a failed hugolint job error message when viewed in the job log:

Newly broken (only in "linkcheck.json", 3 issues):
❌ [content/handbook/security/product-security/_index.md:43]: <major> Link destination "architecture/" does not exist
❌ [content/handbook/security/product-security/security-architecture/_index.md:269]: <major> Link destination "/handbook/business-technology/tech-stack/#panther" does not exist
❌ [content/handbook/security/product-security/security-architecture/zero-trust.md:45]: <major> Link destination "/handbook/security/corporate/systems/#laptop-or-desktop-system-configuration" does not exist

1. The error starts with the file where the broken link is present, followed by the line number. (For example, file path - content/handbook/security/product-security/_index.md, line number: 43.)
2. Next, the error indicates which link is broken. (For example, architecture/ is the broken link destination.)
3. For broken or non-existent anchor links (for example, #panther):
   1. Did the MR change a heading that is being linked to? If so, you’ll need to update the linked anchor to match the new heading.
   2. If you’re linking to a heading, does it exists? Check the file in the repository instead of on the website. The links are checked pre-build, so generated content (from shortcodes and includes) don’t “exist” for the link checker.
      • If the page you’re linking to has a large amount of generated content (such as performance indicator pages), you can add an exclusion to hugolint in the relevant configuration file.

Community contributions

Pipelines for community contributions to the handbook from private forks will fail. Contributors should use a public fork, or preferably the community fork.

Fixing default branch errors

If several unrelated MRs fail with the same error, compare their logs with the latest default-branch pipeline. Ask in #handbook Slack with the job URLs before changing unrelated content. A shared failure may come from configuration, imported data, infrastructure, or a dependency; the log determines where to investigate. See the maintenance guide.

Example: Fixing broken main on tech writing shortcode

This historical incident used older Hugo templates and repository paths. It shows how to follow an error into its source data, rather than commands to copy today.

Consider this example error:

Error: error building site: failed to render shortcode: "/builds/gitlab-com/content-sites/handbook/content/handbook/marketing/product-and-technical-marketing/technical-writing/_index.md:126:1": failed to render shortcode "tech-writing": failed to process shortcode: "/builds/gitlab-com/content-sites/handbook/layouts/shortcodes/tech-writing.html:16:28": execute of template failed: template: shortcodes/tech-writing.html:16:28: executing "shortcodes/tech-writing.html" at <ref page (printf "/handbook/product/categories#%s-section" $section)>: error calling ref: parse "/handbook/product/categories#%!s(<nil>)-section": invalid URL escape "%!s"

Following the error trace, notice that the last error with a full path and line number is: failed to process shortcode: "/builds/gitlab-com/content-sites/handbook/layouts/shortcodes/tech-writing.html:16:28".

Looking at the tech-writing shortcode, the issue is an unexpected value in printf "/handbook/product/categories#%s-section" $section, which matches the last part of the error message.

From there, line 11 of the tech-writing shortcode tells us that the data is from site.Data.public.stages.stages "section".

If you have a local build of the site, you can find all the data files in the data/public folder. The relevant file (usually a yml file) should tell you at the top where to find the original.

If you do not have a local build, you can still likely find it in the www-gitlab-com data folder.

Based on the code, you can figure out the filename. site.Data.public.stages.stages means it’s in data/public and the file is stages.yml.

The last parts .stages "section" means it’s inside of stages: and it’s pulling data from each section: line.

You can check the most recent changes to the file, and/or compare it to when main started failing.

In this case, an empty section: line was the issue.

The quick and easy fix is to add text to the empty section: line, merge it, and run a new pipeline in the public handbook project.

In this case, the handbook code was made more robust.

Prettier is formatting markdown files

If you have prettier set up in VS Code and it is formatting the .md files when they are not supposed to, check if you have Prettier set to be your default formatter with "editor.defaultFormatter": "esbenp.prettier-vscode" in your user settings.

Additionally, consider using the Glob Pattern in the extension settings to specify which files to prettify automatically.

View page source - Edit this page - please contribute.