# Refresh-refcache PR fix

> How to resolve outstanding non-2XX entries on the otelbot refcache-refresh PR.

---

LLMS index: [llms.txt](/llms.txt)

---

Follow these steps to resolve non-2XX `static/refcache.json` entries in the
`otelbot/refcache-refresh` PR. This process may involve updating or removing
dead links on the site, then refreshing the refcache again until no non-2XX
entries remain.

## Preparation

These steps assume you have a local clone of the repository with the `upstream`
remote configured to point to the main repository. Run these steps locally from
the repository root.

1. Determine the PR associated with upstream `otelbot/refcache-refresh`.
2. If none exists, stop.
3. If a local `otelbot/refcache-refresh` branch already exists and contains
   commits that are not in `upstream/otelbot/refcache-refresh`, back them up or
   stop before resetting anything.
4. Check out the PR branch with `gh pr checkout <num>`. If that fails because
   the local branch has diverged and you have already backed up any local-only
   commits, realign it with upstream:

   ```sh
   git fetch upstream
   git checkout otelbot/refcache-refresh
   git reset --hard upstream/otelbot/refcache-refresh
   ```

5. If any content modules are out of date, run `npm run get:submodule`.

## Resolve non-2XX entries

1. Run `./scripts/double-check-refcache-4XX.mjs` to retry transient 4XX failures
   and update `static/refcache.json`.
2. Scan `static/refcache.json` for remaining non-2XX statuses.
3. If none remain, commit and push any changed files (only
   `static/refcache.json` should have changed) to
   `upstream/otelbot/refcache-refresh`, then stop.
4. List remaining non-2XX URLs and their statuses:

   ```sh
   jq -r 'to_entries[] | select(.value.StatusCode < 200 or .value.StatusCode >= 300) | "\(.key) \(.value.StatusCode)"' \
     static/refcache.json
   ```

5. For each remaining status, fix or remove the source link that produced it:
   - For a 404, identify the site pages that refer to the dead URL and update or
     remove that link.
   - For any other non-2XX status, inspect it manually and update or remove the
     source link as needed before continuing.
6. Run `npm run fix:refcache` to refresh `static/refcache.json` after those
   source-link changes, then repeat the steps in this section until no non-2XX
   statuses remain.