openclaw - ✅(Solved) Fix `openclaw update` fails with "Completion cache update failed (qa scenario pack not found)" [1 pull requests, 1 comments, 2 participants]

openclaw2026-04-09 09:35:59

ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

GitHub issue URL

Helpful · Quick feedback

GitHub stats

openclaw/openclaw#63665•Fetched 2026-04-10 03:42:15

View on GitHub

Comments

Participants

Timeline

Reactions

Author

ggzeng

Participants

Artyomkun

ggzeng

Timeline (top)

commented ×1cross-referenced ×1referenced ×1renamed ×1

When running openclaw update, the Completion cache update step produces the following error:

Completion cache update failed ([openclaw] Failed to start CLI: Error: qa scenario pack not found: qa/scenarios/index.md
    at readQaScenarioPack (file:///usr/local/lib/node_modules/openclaw/dist/suite-BW4kSK9C.js:754:27)
    at readQaScenarioById (file:///usr/local/lib/node_modules/openclaw/dist/suite-BW4kSK9C.js:790:19)
    at readQaScenarioExecutionConfig (file:///usr/local/lib/node_modules/openclaw/dist/suite-BW4kSK9C.js:795:9)
    at readRequiredDiscoveryRefs (file:///usr/local/lib/node_modules/openclaw/dist/suite-BW4kSK9C.js:2834:9)
    at file:///usr/local/lib/node_modules/openclaw/dist/suite-BW4kSK9C.js:2840:39

Error Message

Completion cache update failed ([openclaw] Failed to start CLI: Error: qa scenario pack not found: qa/scenarios/index.md at readQaScenarioPack (file:///usr/local/lib/node_modules/openclaw/dist/suite-BW4kSK9C.js:754:27) at readQaScenarioById (file:///usr/local/lib/node_modules/openclaw/dist/suite-BW4kSK9C.js:790:19) at readQaScenarioExecutionConfig (file:///usr/local/lib/node_modules/openclaw/dist/suite-BW4kSK9C.js:795:9) at readRequiredDiscoveryRefs (file:///usr/local/lib/node_modules/openclaw/dist/suite-BW4kSK9C.js:2834:9) at file:///usr/local/lib/node_modules/openclaw/dist/suite-BW4kSK9C.js:2840:39

Root Cause

Root Cause Analysis

Fix Action

Fixed

Fixed by PR: fix: make readQaScenarioPack return null instead of throwing when files are missing (https://github.com/openclaw/openclaw/pull/63679)

PR fix notes

PR #63679: fix: make readQaScenarioPack return null instead of throwing when files are missing

Repository: openclaw/openclaw
Author: ggzeng
State: open | merged: False
Link: https://github.com/openclaw/openclaw/pull/63679

Description (problem / solution / changelog)

Summary

Make readQaScenarioPack() return null instead of throwing when QA scenario files are missing
Make readQaBootstrapScenarioCatalog() return null instead of throwing in the same case

Closes #63665

Problem

When OpenClaw is installed via npm globally, the qa/ directory is not included in the published package (not listed in package.json files). However, readQaScenarioPack() throws an error when the file is not found. This function is called during module initialization in some code paths (e.g., via readRequiredDiscoveryRefs()), causing the completion cache update step in openclaw update to fail with:

Completion cache update failed (Error: qa scenario pack not found: qa/scenarios/index.md)

Fix

Changed readQaScenarioPack() and readQaBootstrapScenarioCatalog() to return null instead of throwing when QA scenario files are not present. This is the expected state in npm global installations — only source checkouts include the qa/ directory.

Files changed

extensions/qa-lab/src/scenario-catalog.ts — Return null instead of throwing; updated return types to QaScenarioPack | null and QaBootstrapScenarioCatalog | null

Notes for reviewers

Callers of these functions (qa-agent-bootstrap.ts, qa-agent-workspace.ts, lab-server.ts) all operate within the QA Lab extension, which only runs in source checkout environments. In npm installs, the entire QA Lab CLI command group is registered lazily and these code paths are not reached during normal operation. The callers may want to add explicit null checks for type safety, but this is not required to fix the reported issue.

Test plan

Existing test scenario-catalog.test.ts passes in source checkout (files exist, returns non-null)
Verify openclaw update no longer shows "Completion cache update failed" warning in npm global install
Verify openclaw completion --write-state succeeds in npm global install

Changed files

extensions/qa-lab/src/lab-server.ts (modified, +6/-2)
extensions/qa-lab/src/qa-agent-bootstrap.ts (modified, +4/-1)
extensions/qa-lab/src/qa-agent-workspace.ts (modified, +3/-0)
extensions/qa-lab/src/scenario-catalog.test.ts (modified, +9/-0)
extensions/qa-lab/src/scenario-catalog.ts (modified, +23/-6)
extensions/qa-lab/src/suite.ts (modified, +7/-5)

Code Example

Completion cache update failed ([openclaw] Failed to start CLI: Error: qa scenario pack not found: qa/scenarios/index.md
    at readQaScenarioPack (file:///usr/local/lib/node_modules/openclaw/dist/suite-BW4kSK9C.js:754:27)
    at readQaScenarioById (file:///usr/local/lib/node_modules/openclaw/dist/suite-BW4kSK9C.js:790:19)
    at readQaScenarioExecutionConfig (file:///usr/local/lib/node_modules/openclaw/dist/suite-BW4kSK9C.js:795:9)
    at readRequiredDiscoveryRefs (file:///usr/local/lib/node_modules/openclaw/dist/suite-BW4kSK9C.js:2834:9)
    at file:///usr/local/lib/node_modules/openclaw/dist/suite-BW4kSK9C.js:2840:39

---

openclaw update
  → tryWriteCompletionCache()               (src/cli/update-cli/shared.ts)
    → spawnSync("node openclaw.mjs completion --write-state")
      → Register all CLI command groups (including QA commands)
        → readRequiredDiscoveryRefs()        (module-level side effect)
          → readQaScenarioExecutionConfig("source-docs-discovery-report")
            → readQaScenarioById()
              → readQaScenarioPack()
                → readTextFile("qa/scenarios/index.md")
                → File not found → throw Error

---

export function readQaScenarioPack(): QaScenarioPack {
  const markdown = readQaScenarioPackMarkdown();
  if (!markdown) {
    throw new Error(`qa scenario pack not found: ${QA_SCENARIO_PACK_PATH}`);  // ← triggered in npm installs
  }
  // ...
}

RAW_BUFFERClick to expand / collapse

Description

When running openclaw update, the Completion cache update step produces the following error:

Completion cache update failed ([openclaw] Failed to start CLI: Error: qa scenario pack not found: qa/scenarios/index.md
    at readQaScenarioPack (file:///usr/local/lib/node_modules/openclaw/dist/suite-BW4kSK9C.js:754:27)
    at readQaScenarioById (file:///usr/local/lib/node_modules/openclaw/dist/suite-BW4kSK9C.js:790:19)
    at readQaScenarioExecutionConfig (file:///usr/local/lib/node_modules/openclaw/dist/suite-BW4kSK9C.js:795:9)
    at readRequiredDiscoveryRefs (file:///usr/local/lib/node_modules/openclaw/dist/suite-BW4kSK9C.js:2834:9)
    at file:///usr/local/lib/node_modules/openclaw/dist/suite-BW4kSK9C.js:2840:39

Environment

OpenClaw version: 2026.4.9 (npm global install)
Install method: npm i -g openclaw
Platform: macOS (Darwin 25.3.0)

Root Cause Analysis

Call chain

openclaw update
  → tryWriteCompletionCache()               (src/cli/update-cli/shared.ts)
    → spawnSync("node openclaw.mjs completion --write-state")
      → Register all CLI command groups (including QA commands)
        → readRequiredDiscoveryRefs()        (module-level side effect)
          → readQaScenarioExecutionConfig("source-docs-discovery-report")
            → readQaScenarioById()
              → readQaScenarioPack()
                → readTextFile("qa/scenarios/index.md")
                → File not found → throw Error

Details

tryWriteCompletionCache() spawns a child process after update completes to refresh the shell completion cache via openclaw completion --write-state.
The completion command must register all CLI command groups, including the QA command group.
The QA module's readRequiredDiscoveryRefs() is invoked at module level as the initializer for the REQUIRED_DISCOVERY_REFS_LOWER constant — it runs immediately on import.
This function calls readQaScenarioPack() which attempts to read qa/scenarios/index.md.
The npm package's package.json files field does not include the qa/ directory, so the file does not exist in npm installations.
readQaScenarioPack() throws an error when the file is not found.

Key code

The problematic code in scenario-catalog.ts:

export function readQaScenarioPack(): QaScenarioPack {
  const markdown = readQaScenarioPackMarkdown();
  if (!markdown) {
    throw new Error(`qa scenario pack not found: ${QA_SCENARIO_PACK_PATH}`);  // ← triggered in npm installs
  }
  // ...
}

Impact

The error does not affect core functionality — it only prevents the shell completion cache from being refreshed.
The update itself completes successfully, but displays a warning at the end.
All users who install OpenClaw via npm globally will encounter this issue when running openclaw update.

Suggested Fix

Option A (Recommended): In scenario-catalog.ts, make readQaScenarioPack() return null instead of throwing when the file does not exist. Update callers (readQaBootstrapScenarioCatalog(), etc.) to handle null gracefully.

Option B: Change readRequiredDiscoveryRefs() from a module-level constant initializer to a lazy-evaluated function.

Option C: Add qa/ to package.json files (not recommended — increases package size for files only needed in development).

Steps to Reproduce

Install OpenClaw globally via npm: npm i -g openclaw
Run openclaw update
Observe the "Completion cache update failed" warning in the output

extent analysis

TL;DR

Modify the readQaScenarioPack() function to return null instead of throwing an error when the qa/scenarios/index.md file is not found.

Guidance

Identify the callers of readQaScenarioPack() and update them to handle null returns gracefully.
Consider implementing a lazy-evaluation approach for readRequiredDiscoveryRefs() to avoid module-level execution.
Verify the fix by running openclaw update and checking for the absence of the "Completion cache update failed" warning.

Example

export function readQaScenarioPack(): QaScenarioPack | null {
  const markdown = readQaScenarioPackMarkdown();
  if (!markdown) {
    return null;  // Return null instead of throwing
  }
  // ...
}

Notes

The proposed fix assumes that returning null from readQaScenarioPack() will not break existing functionality. It's essential to test the changes thoroughly to ensure that the completion cache update works as expected.

Recommendation

Apply the workaround by modifying the readQaScenarioPack() function to return null when the file is not found, as this approach is recommended in the issue description and seems to be the most straightforward solution.

Vote matrix · Quick signals

Works

Did the solution work? Tap to confirm.

Easy Fix

Was it a quick fix?

Time Saver

Did it save you time?

Blocking

Was it severely blocking?

Common Issue

Are others likely hitting this too?

Flaky / Intermittent

Is it intermittent?

Verified / Reproducible

Can you reproduce it reliably?

#installation #environment variable #network issue #logging issue #file not found

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

openclaw - ✅(Solved) Fix `openclaw update` fails with "Completion cache update failed (qa scenario pack not found)" [1 pull requests, 1 comments, 2 participants]

Recommended Tools

GitHub issue graph ai analysis

Error Message

Root Cause

Root Cause Analysis

Fix Action

Fixed

PR fix notes

PR #63679: fix: make readQaScenarioPack return null instead of throwing when files are missing

Description (problem / solution / changelog)

Summary

Problem

Fix

Files changed

Notes for reviewers

Test plan

Changed files

Code Example

Description

Environment

Root Cause Analysis

Call chain

Details

Key code

Impact

Suggested Fix

Steps to Reproduce

extent analysis

TL;DR

Guidance

Example

Notes

Recommendation

Still need to ship something?

RELATED_DISCOVERY

TRENDING