Issue Station
Sign In
Tools hereToolbox

openclaw - ✅(Solved) Fix [Bug] matrix/doctor: channels.matrix.dm.policy 'trusted' rejected after 2026.4.7 upgrade with no doctor migration [1 pull requests, 1 participants]

Official PRs (…)
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.

Helpful · Quick feedback

Loading…
GitHub stats
openclaw/openclaw#62931•Fetched 2026-04-09 08:00:30
View on GitHub
Comments
0
Participants
1
Timeline
8
Reactions
0
Author
lukeboyettlukeboyett
Participants
lukeboyettlukeboyett
Timeline (top)
referenced ×5closed ×1cross-referenced ×1renamed ×1

Error Message

The offending value is "policy": "trusted", which had been present in the config for ~2 months across multiple OpenClaw versions without any prior validation error or deprecation warning. Running openclaw doctor --fix does not migrate or correct the value — it only re-reports the validation error: This contradicts the error message own advice (Run: openclaw doctor --fix).

Fix Action

Workaround

Manually edit ~/.openclaw/openclaw.json:

 "channels": {
   "matrix": {
     "dm": {
       "enabled": true,
-      "policy": "trusted",
+      "policy": "allowlist",
       "allowFrom": ["@user:example.com"]
     }
   }
 }

PR fix notes

PR #62942: fix(matrix/doctor): migrate legacy channels.matrix.dm.policy 'trusted' (fixes #62931)

Description (problem / solution / changelog)

Summary

Adds a doctor compatibility migration for the legacy channels.matrix.dm.policy: "trusted" value, which is no longer accepted by the schema as of 2026.4.7. Without this migration the gateway hard-fails to start with a validation error, and openclaw doctor --fix (which the error message itself recommends) is a no-op for this case.

Fixes #62931

Problem

In 2026.4.7 the schema for channels.matrix.dm.policy accepts only "pairing" | "allowlist" | "open" | "disabled". Configs that previously held "trusted" (which appears to have been silently accepted in earlier releases) now fail validation:

Config invalid
File: ~/.openclaw/openclaw.json
Problem:
  - channels.matrix.dm.policy: Invalid option: expected one of "pairing"|"allowlist"|"open"|"disabled"

Run: openclaw doctor --fix

openclaw doctor --fix had no migration for this case and only re-printed the same validation error, contradicting its own advice. The user has to hand-edit the config file to recover, and the breaking enum change is not called out in the 2026.4.7 release notes.

Fix

Adds migrateLegacyTrustedDmPolicy() to extensions/matrix/src/doctor-contract.ts and wires it into normalizeCompatibilityConfig() for both the top-level channels.matrix.dm path and the per-account channels.matrix.accounts.<id>.dm path.

The migration uses the safest semantically-equivalent mapping:

Legacy stateMigrated toRationale
policy: "trusted" + non-empty allowFrom"allowlist"Preserves the explicit allowlist semantics that "trusted" had.
policy: "trusted" + no allowFrom"pairing"Defaults to the secure mode rather than silently widening access on upgrade.

Two new legacyConfigRules entries are also added so the issue surfaces under the existing "Legacy config keys detected" channel before --fix is applied.

This works because readConfigFileSnapshotInternal preserves sourceConfig even when validation fails (src/config/io.ts:1307), so the doctor flow reaches normalizeCompatibilityConfig with the raw object containing the legacy value.

Test plan

  • pnpm vitest run extensions/matrix/src/doctor.test.ts — 9 passed, 0 failed (5 existing + 4 new)
  • pnpm tsgo — 0 errors
  • pnpm lint (oxlint --type-aware) — 0 warnings, 0 errors over 10663 files
  • All pre-commit gates: conflict markers, host-env policy, webhook auth, pairing scope, tool-display
  • Manual repro: a ~/.openclaw/openclaw.json with channels.matrix.dm.policy: "trusted" + allowFrom list now migrates cleanly to "allowlist" via openclaw doctor --fix, and the gateway starts successfully on the next run.

New test cases cover:

  1. Top-level dm.policy: "trusted" + allowFrom → "allowlist" (preserves entries)
  2. Top-level dm.policy: "trusted" + no allowFrom → "pairing" (safe default)
  3. Per-account variant with both shapes in the same accounts map
  4. Modern "allowlist" / "pairing" values are passed through untouched (no-op)

Out of scope

This PR only addresses the migration. It does not:

  • Add "trusted" back as a permanent schema alias (a deprecation-window approach would also be reasonable but is more invasive)
  • Touch the 2026.4.7 release notes to retroactively flag the breaking change
  • Change the original commit that removed the enum value

Either of those would be reasonable follow-ups but are independent of restoring doctor --fix to a working state.

🤖 Generated with Claude Code

Changed files

  • CHANGELOG.md (modified, +1/-0)
  • extensions/matrix/src/doctor-contract.ts (modified, +77/-0)
  • extensions/matrix/src/doctor.test.ts (modified, +195/-0)

Code Example

Config invalid
File: ~/.openclaw/openclaw.json
Problem:
  - channels.matrix.dm.policy: Invalid option: expected one of "pairing"|"allowlist"|"open"|"disabled"

Run: openclaw doctor --fix

---

Invalid config:
- channels.matrix.dm.policy: Invalid option: expected one of "pairing"|"allowlist"|"open"|"disabled"
│
└  Doctor complete.

---

"channels": {
   "matrix": {
     "dm": {
       "enabled": true,
-      "policy": "trusted",
+      "policy": "allowlist",
       "allowFrom": ["@user:example.com"]
     }
   }
 }
RAW_BUFFERClick to expand / collapse

Bug Report

Upgrading from v2026.4.5 to v2026.4.7 causes the gateway to fail validation and refuse to start with:

Config invalid
File: ~/.openclaw/openclaw.json
Problem:
  - channels.matrix.dm.policy: Invalid option: expected one of "pairing"|"allowlist"|"open"|"disabled"

Run: openclaw doctor --fix

The offending value is "policy": "trusted", which had been present in the config for ~2 months across multiple OpenClaw versions without any prior validation error or deprecation warning.

Severity

Stealth breaking change. The 2026.4.7 release notes do not contain a ### Breaking section and make no mention of this enum change. The gateway hard-fails to start, which is an unfortunate failure mode mid-upgrade.

Doctor does not migrate

Running openclaw doctor --fix does not migrate or correct the value — it only re-reports the validation error:

Invalid config:
- channels.matrix.dm.policy: Invalid option: expected one of "pairing"|"allowlist"|"open"|"disabled"
│
└  Doctor complete.

This contradicts the error message own advice (Run: openclaw doctor --fix).

Reproduction

  1. Have a Matrix DM config with channels.matrix.dm.policy: "trusted" and an allowFrom allowlist (any prior-version config that originated this value will do)
  2. Upgrade to v2026.4.7
  3. Start the gateway → hard-fails with Config invalid
  4. Run openclaw doctor --fix → does not migrate

Environment

  • OpenClaw: 2026.4.7 (upgraded from 2026.4.5)
  • Platform: macOS LaunchDaemon
  • Node: 25.6.0

Expected Behavior

One of:

  1. doctor --fix migrates the value automatically. A "trusted" policy with an allowFrom list maps cleanly to "allowlist" (which is what I had to do manually). A "trusted" policy without an allowlist could map to "pairing".
  2. The release notes call out the breaking enum change under ### Breaking, with explicit migration instructions.
  3. Backward-compat: silently accept "trusted" as an alias for "allowlist" for some grace period, with a deprecation warning.

Currently none of these happen — the gateway refuses to start and doctor is non-functional for this case.

Workaround

Manually edit ~/.openclaw/openclaw.json:

 "channels": {
   "matrix": {
     "dm": {
       "enabled": true,
-      "policy": "trusted",
+      "policy": "allowlist",
       "allowFrom": ["@user:example.com"]
     }
   }
 }

Additional Context

Looking at the v2026.4.5..v2026.4.7 git range, the most likely culprit is the Matrix invite auto-join refactor (Matrix: prompt invite auto-join during onboarding (#62168)), which restructured extensions/matrix/src/onboarding.ts and adjacent config-update paths. The current canonical enum lives at extensions/matrix/src/matrix/monitor/verification-events.ts as "open" | "pairing" | "allowlist" | "disabled". There is no fallback for legacy "trusted" in any code path I could find.

🤖 Generated with Claude Code

extent analysis

TL;DR

Manually editing the openclaw.json file to replace the "trusted" policy with "allowlist" or another valid option is the most likely fix.

Guidance

  • Verify that the openclaw.json file contains the offending "policy": "trusted" value and update it to one of the valid options ("pairing", "allowlist", "open", or "disabled").
  • Check the release notes for any future updates that may address this breaking change and provide a more automated migration path.
  • If using a version prior to v2026.4.7, consider delaying the upgrade until a fix or proper migration instructions are provided.
  • Test the gateway after applying the manual fix to ensure it starts correctly and functions as expected.

Example

The provided workaround code snippet demonstrates the necessary change:

 "channels": {
   "matrix": {
     "dm": {
       "enabled": true,
-      "policy": "trusted",
+      "policy": "allowlist",
       "allowFrom": ["@user:example.com"]
     }
   }
 }

Replace the "trusted" policy with "allowlist" (or another valid option) in the openclaw.json file.

Notes

The openclaw doctor --fix command does not currently migrate the "trusted" policy value, so a manual edit is required. The lack of a ### Breaking section in the release notes and the absence of a deprecation warning make this a stealth breaking change.

Recommendation

Apply the workaround by manually editing the openclaw.json file, as the current version of openclaw doctor --fix does not provide a functional migration path.

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?
Loading…
#index setup#retrieval issue#search optimization#API routing#API middleware

Still need to ship something?

×6

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

Back to top recommendations

TRENDING