BlueBubbles Config Bug: OpenClaw May Write an Invalid Key and Fail on Next Restart (v2026.3.28)

A newly reported BlueBubbles regression in OpenClaw 2026.3.28 can turn a normal restart into a startup failure.

The dangerous part is not just “invalid config.” It is that the gateway appears to write the problematic key itself, then refuses to start once that key is present in openclaw.json.

Source:

• Issue report: openclaw/openclaw#58460

What operators actually see

The reported failure pattern is:

1. BlueBubbles is configured with the usual required fields.
2. The gateway starts successfully once.
3. During or after startup, openclaw.json gains:

"enrichGroupParticipantsFromContacts": true

4. On the next restart, the gateway rejects that key as unrecognized.
5. The service no longer starts cleanly until the key is removed manually.

That means operators experience this as a self-inflicted config brick, not as a normal typo.

Why this is a high-impact bug

This bug is operationally worse than a normal validation error for three reasons.

1) The system appears to create its own invalid state

If the user never added the key manually, the recovery path becomes much harder to trust. People stop assuming “restart is safe.”

2) Restart turns into an outage boundary

A configuration that seemed valid during the first startup can become fatal during the second startup. That makes maintenance windows and routine restarts risky.

3) Auto-restart setups can amplify the damage

If your host keeps trying to revive the gateway automatically, the process can fall into a repeat crash loop instead of staying down cleanly with one obvious error.

How to confirm you hit the same issue

You are likely seeing the same bug shape if all of the following are true:

• OpenClaw version is near 2026.3.28
• you use the BlueBubbles channel
• your config originally worked without the extra key
• after one successful start, openclaw.json now contains enrichGroupParticipantsFromContacts
• the next restart fails with an “unrecognized key” style error for that exact field

A practical check sequence:

1. Back up ~/.openclaw/openclaw.json.
2. Confirm whether the BlueBubbles block currently contains enrichGroupParticipantsFromContacts.
3. Check file modification time and compare it with the last gateway startup window.
4. Restart once and capture the validation error.
5. Remove only that key, then test whether the gateway starts again.

If removing that one field restores startup, the reported pattern is a strong match.

What this is not

Do not confuse this with these adjacent problems:

• a user manually added an unsupported BlueBubbles option
• a malformed JSON edit introduced a syntax error
• a packaging issue removed the entire BlueBubbles schema block
• the gateway fails before BlueBubbles config validation even runs

This report is narrower: the same gateway that wrote the key later rejects it.

Likely root-cause boundary

The issue report points to a schema round-trip problem:

• one code path parses config with a default value for enrichGroupParticipantsFromContacts
• the parsed result is written back to disk
• a later validation path rejects the persisted key as unknown

In plain language, the gateway may be mixing parse-time defaults with strict persisted-config validation in a way that is not internally consistent.

That would explain why first boot works and second boot fails.

Practical mitigation until upstream fixes it

1) Treat restart as a verification event, not a routine click

After any restart involving BlueBubbles, immediately confirm that the gateway actually came back healthy.

2) Keep a clean backup of the working config

Before restarting, save a known-good copy of openclaw.json. When config can self-drift, rollback speed matters more than elegance.

3) Remove only the offending field if you hit the loop

If logs point specifically to enrichGroupParticipantsFromContacts, do the smallest reversible edit possible. Avoid broad config surgery during incident handling.

4) Disable aggressive blind auto-restart while debugging

If the process manager keeps relaunching a broken config instantly, it becomes harder to capture logs and verify whether the failure is stable.

Fast operator checklist

If you only need the shortest path:

1. inspect channels.bluebubbles in openclaw.json
2. look for enrichGroupParticipantsFromContacts
3. if restart fails on that key, remove it temporarily
4. restart once more and confirm recovery
5. archive logs and config diff for the upstream bug report

What to include in a good follow-up report

If you are confirming or extending the upstream report, include:

• exact OpenClaw version
• install method (npm, source build, etc.)
• OS and architecture
• whether the key was absent before first launch
• whether the gateway wrote the key during startup
• the exact validation error on the next restart
• whether removing the key immediately restores startup

That evidence is much more useful than saying “BlueBubbles broke after restart.”

FAQ: the three judgment calls operators usually make first

If BlueBubbles is live in production, should I avoid restarting entirely?

No, but you should stop treating restart as a harmless routine action. Until upstream closes this bug shape, every restart should be followed by an explicit health check so you can catch config drift before it becomes a longer outage.

If removing the key brings the gateway back, is that enough to close the incident?

It is enough to restore service, not enough to close the incident. You still need to preserve the broken config, the validation error, and the version/install context, otherwise the next restart window may reproduce the same failure with no better evidence.

What is the safest handoff note for an on-call teammate?

Tell them one thing very clearly: if BlueBubbles fails right after restart, inspect channels.bluebubbles.enrichGroupParticipantsFromContacts before doing broad config edits. That single note shortens time-to-recovery and reduces accidental over-editing.

How can operators quickly tell whether this is schema injection, not bad contact data or a random BlueBubbles outage?

Use the failure sequence, not guesswork.

You are much more likely dealing with schema injection when:

• the first startup succeeds, so BlueBubbles connectivity looked normal initially
• the config file gains enrichGroupParticipantsFromContacts without an operator intentionally adding it
• the next restart fails during config validation on that exact key
• removing only that field restores startup immediately

That pattern points to a config round-trip problem. It does not look like bad contact sync, broken group metadata, or a generic transport outage.

What should you verify right after patching or working around BlueBubbles group-send flows?

After the service comes back, do a short post-fix check instead of stopping at “the process is running again.”

Verify these in order:

1. the gateway survives a clean second restart without reintroducing the bad key
2. openclaw.json stays stable and does not rewrite enrichGroupParticipantsFromContacts
3. one real BlueBubbles path, especially a group-send or participant-related flow, still works as expected
4. your process manager is no longer looping on stale crash-restart behavior
5. the saved incident notes include the broken config snapshot and exact validation error

That second restart check is especially important because this bug is dangerous precisely when startup one succeeds and startup two fails.

Preserve these four artifacts before the second restart

The key failure is not whether the first startup works. It is whether BlueBubbles config gets written back in a shape that makes the second startup fail schema validation. Before restarting again, preserve four artifacts:

1. Original BlueBubbles config snippet: especially whether enrichGroupParticipantsFromContacts was missing, undefined, or already set to a default value.
2. Config diff after the first startup: prove whether the gateway or plugin wrote the default field back to local config.
3. Full validation error from the second startup: keep the field path, expected type, and actual value instead of only the final log line.
4. Bypass comparison result: after deleting the field or rolling back the config, record whether the gateway starts again.

These artifacts turn “BlueBubbles is broken” into a narrower mismatch between default injection and zod validation. That is much more useful for an upstream issue, a patch, or a rollback decision.

If you arrived from ACPX, Feishu /stop, or gateway-restart paths

Those entry paths can all sound like “the gateway is unstable again,” but this BlueBubbles failure is not primarily a session-lifecycle bug or an interrupt-routing bug. It is a config round-trip that can make the next startup fail. Split the intent first:

• A Claude ACP task starts with no usable session ID: start with the ACPX silent-session troubleshooting page, where the creation path fails.
• A Feishu thread keeps running and /stop or /new does not interrupt it: start with the Feishu /stop troubleshooting page, where the control command does not stop the execution layer.
• Sessions are not recovered after a gateway crash/restart: start with the orphaned sessions recovery page, where the runtime recovery chain is the problem.
• Startup one succeeds, startup two fails on enrichGroupParticipantsFromContacts validation: then use this page, preserve the bad config, remove the key, and run the second-restart check.

This routing keeps “session was never created,” “run will not stop,” “runtime state did not recover,” and “BlueBubbles config mutation prevents gateway startup” in separate buckets. That reduces wrong mitigations and turns search traffic into the correct recovery path faster.

Exact searches this BlueBubbles gateway bug page should answer next

Use this section when a reader lands from a narrow BlueBubbles or Zod default query and needs to decide whether the failure is a schema issue, a contact enrichment issue, or a gateway packaging issue.

• BlueBubbles gateway injects Zod default enrichGroupParticipantsFromContacts: check whether the generated gateway schema is adding a default that the real BlueBubbles action does not expect.
• OpenClaw BlueBubbles enrichGroupParticipantsFromContacts default bug: compare the action input schema with the payload that reaches the plugin before blaming contacts sync.
• fix BlueBubbles gateway Zod default group participants: remove or override the generated default, then rerun the same group chat enrichment call as a smoke test.

Turn BlueBubbles error traffic into a minimal debug path

If you arrived from searches around enrichGroupParticipantsFromContacts, Zod defaults, or BlueBubbles gateway errors, do not start by rewriting contact sync logic. First confirm the input shape, the plugin-level default, and the payload difference before and after Gateway forwarding, then decide whether OpenClaw needs a schema guard.

A minimal debug path is three steps: preserve one failing payload, replay the same BlueBubbles event, and compare field changes before and after the default injection. Only promote it to a plugin compatibility fix when the failure is reproducible and the injected default actually changes contact-enrichment behavior. Otherwise, keep it out of the generic network or account-problem bucket.

Related reading

• Gateway Does Not Resume Orphaned Sessions After Crash/Restart: How to Confirm, Contain, and Recover
• Troubleshooting OpenClaw Agents: What to Check When Tasks Stall or Tools Misbehave
• OpenClaw Complete Installation Guide: Self-Host Setup, Checks, and Common Pitfalls

Why this topic is worth publishing separately

This article is not the same as our earlier session-recovery coverage.

That earlier piece was about runtime recovery after crash/restart. This one is about config mutation + validation mismatch that can stop the gateway from starting at all.

Different failure surface, different operator intent, different search behavior.

On-call runbook: decide within 10 minutes whether to delete the key, roll back, or escalate

When this page is the first landing page from search, operators usually do not need the full background first. They need to recover the gateway within 10 minutes. Use this short runbook:

1. Freeze the scene first: copy the current openclaw.json, the diff after the last successful startup, and the zod validation error from the second startup.
2. Use the smallest bypass: if the error only points at channels.bluebubbles.enrichGroupParticipantsFromContacts, remove that key first and avoid broad BlueBubbles config edits.
3. Run the second-restart check: after recovery, restart once more immediately and confirm the bad field is not written back.
4. Decide whether to roll back: if the field keeps coming back, or deletion still does not restore startup, escalate to plugin version, gateway version, and recent config migrations.
5. Attach upstream evidence: send maintainers the bad config, recovery diff, version, install method, and both startup logs together.

This runbook keeps a config round-trip bug from turning into a full config rewrite. It also tells high-intent visitors when to contain locally and when to escalate.

After the incident, add these five checks to the restart SOP

Recovering the gateway is only the first step. To avoid rediscovering the same failure during the next maintenance window, add these five checks to the BlueBubbles restart SOP:

1. Back up config before restart: preserve openclaw.json and the BlueBubbles channel block, not only process logs.
2. Diff config immediately after restart: check whether enrichGroupParticipantsFromContacts was added, removed, or rewritten.
3. Require a second restart: the first successful startup is not enough; the gateway must survive startup two.
4. Validate a real group path: run at least one real group or participant-related BlueBubbles flow instead of trusting only a health endpoint.
5. Define escalation triggers: if the bad field is written back, deletion still fails, or schema errors spread to other fields, stop guessing locally and escalate to maintainers.

This turns “BlueBubbles broke again” into a reproducible, handoff-ready, escalation-ready maintenance flow for high-intent operators arriving from GA4-driven search.

If you landed here from search, separate these three nearby failures first

GA4 shows this landing page is already attracting repeat operator traffic. To reduce wrong mitigations, split the similar failure shapes before changing config:

1. Startup fails after a config field is written back: this article's pattern, usually involving enrichGroupParticipantsFromContacts, zod validation, and a second restart.
2. The BlueBubbles API itself is unreachable: check service URL, token, network, and the phone bridge before deleting OpenClaw config fields.
3. The gateway starts but group-send still fails: inspect send logs and participant resolution instead of relying on startup logs alone.

For on-call triage, the fastest test is: find the second-startup schema error, then confirm whether the field was automatically written back. Only when both are true should you follow this page's remove, retest, and escalate path.

False-positive checks before you delete BlueBubbles config

Before removing a generated BlueBubbles field, rule out three false positives: a manually edited contact field, a stale mobile companion cache, and a gateway process that is still reading an older config snapshot. Capture the bad key, the process start time, and one clean restart result before you call it an OpenClaw injection regression.

This matters for search visitors because the recovery action is different. A schema-injection regression should be fixed by removing the invalid generated field and preventing the writer from recreating it; a stale BlueBubbles cache should be fixed by refreshing the messaging side without rewriting OpenClaw gateway config.

Source

• openclaw/openclaw#58460