Skip to content

docs(channels): update troubleshooting.md — ID-based channel ACL + silent-drop migration symptom (post-netclaw-dev/netclaw#1368) #61

Description

@Aaronontheweb

Context

Update src/content/docs/channels/troubleshooting.md after netclaw-dev/netclaw#1368 ships.

Current

  • "Run netclaw init" as the fix for token/channel configuration issues
  • Fix examples reference raw DefaultChannelName / DefaultChannelId fields
  • No mention of the display-name → canonical-ID migration introduced in #1368

Should become

  • Replace "run netclaw init" token-fix instructions with "run netclaw config → Channels"
  • New symptom section: "Channel messages silently dropped after upgrading from pre-0.24.0"
    • Cause: AllowedChannelIds held display names (e.g. #general) that no longer match canonical IDs after the upgrade — the ACL check fails silently
    • Fix: Re-enter the channel list via netclaw config → Channels (resolve-before-add stores canonical IDs automatically)
    • Manual JSON fix (for advanced users): replace display names with canonical IDs; add a "config does this automatically" note
  • Retain existing diagnostic steps for other symptoms; update any netclaw init re-run instructions to use the new action menu (Redo Identity / Open config editor / Start over / Cancel)

Screenshots or tapes needed

None required — prose/copy update. Optionally include config-channels-resolve from sub-issue #13 if helpful.

Acceptance criteria

  • "Run netclaw init" token-fix replaced with netclaw config
  • New "silent drop after upgrade" symptom documented with cause + fix
  • Manual JSON fix retained with "config does this automatically" note
  • Any remaining netclaw init re-run references updated to action menu

Dependencies

Part of #55

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Type

    No type

    Fields

    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions