OpenClaw 4.5 notifyActiveTaskWaiters TypeError crashes Discord gateway

Primary Manifestation

The Discord gateway crashes with a TypeError upon receiving any incoming message. The bot becomes completely non-responsive with no replies sent.

Error Output

TypeError: undefined is not iterable (cannot read property 'length' of undefined)
  at notifyActiveTaskWaiters (command-queue.ts)
  → Gateway handler crashes before any reply can be sent
  → All Discord messages silently dropped

Behavioral Symptoms

• Bot accepts the WebSocket connection successfully
• No acknowledgment of received messages in logs
• Discord shows no bot response to user messages
• Gateway connection remains active but idle
• Other plugin functionality may be affected depending on command queue usage

Environment

• OpenClaw Version: 2026.4.5
• Node.js: v22.22.1
• OS: Linux (Ubuntu)
• Channel: Discord

Direct Cause

The notifyActiveTaskWaiters function in command-queue.ts receives an undefined value where it expects an iterable array. The function attempts to access the .length property or iterate over this value without a guard clause, triggering the TypeError.

Failure Sequence

1. User sends a message to the Discord bot
2. Gateway receives the message payload via WebSocket
3. Gateway handler invokes notifyActiveTaskWaiters
4. notifyActiveTaskWaiters receives undefined instead of an array
5. Internal iteration or length check fails on undefined
6. TypeError propagates up the call stack
7. Gateway handler crashes without processing the message

Contributing Configuration Issues

During diagnosis, secondary configuration problems were identified that compound the issue:

• Malformed config nesting: Configuration was nested/duplicated inside itself with a malformed "cha" key, indicating corrupted config.yml
• Removed legacy key: channels.discord.guilds.<id>.channels.<id>.allow was removed in OpenClaw 4.5 but still present in the config
• Missing plugin declarations: discord and anthropic plugins were absent from plugins.allow
• Stale plugin reference: browser existed in plugins.allow referencing a plugin removed in a prior version

Architectural Context

The command queue system manages async task coordination between the gateway and plugin execution. In version 4.5, a code change introduced a dependency on an array that may not always be populated under certain configuration states, particularly when plugin declarations are incomplete or legacy keys conflict with the new schema.

Immediate Workaround: Rollback (Recommended for Production)

If immediate Discord functionality is required:

# Roll back to last known stable version
npm install [email protected]

# Restart the gateway
openclaw restart

Permanent Fix: Configuration Remediation

Execute the built-in diagnostic and repair tool:

openclaw doctor --fix

This command automatically addresses:

• Corrupted or nested configuration structures
• Legacy keys removed in version 4.5
• Missing plugin declarations
• Stale plugin references

Manual Configuration Repair (if doctor fails)

Step 1: Backup current config

cp config.yml config.yml.backup-$(date +%Y%m%d)

Step 2: Remove legacy channel allow keys

Locate and remove all instances of:

channels:
  discord:
    guilds:
      <guild-id>:
        channels:
          <channel-id>:
            allow: [...]  # REMOVE THIS KEY COMPLETELY

Step 3: Fix plugins.allow section

Replace your plugins.allow block with the correct plugin list:

# Before (broken)
plugins:
  allow:
    - browser  # STALE - remove this
    # Missing: discord, anthropic

# After (correct)
plugins:
  allow:
    - discord
    - anthropic
    # Add other active plugins as needed

Step 4: Validate configuration structure

openclaw config validate

Step 5: Restart gateway

openclaw restart

After Fix: Verify Plugin Declaration

openclaw plugins list --enabled

Confirm that discord appears in the enabled plugins list.

Step 1: Confirm Config Validity

openclaw config validate

Expected output:

✓ Configuration schema validated
✓ No legacy keys detected
✓ Plugin declarations complete

Step 2: Run Diagnostic Tool

openclaw doctor

Expected output (no errors):

Checking configuration... OK
Checking plugin declarations... OK
Checking Discord gateway connectivity... OK
No issues found.

Step 3: Verify Gateway Connection

openclaw status --channel discord

Expected output:

Discord Gateway: CONNECTED
Bot User: <your-bot-name>
Latency: <value>ms

Step 4: Functional Test

Send a test message to the bot in Discord. Verify:

• Message is received and logged in gateway output
• Bot responds within expected latency
• No TypeError appears in gateway logs

Step 5: Check Logs for Errors

openclaw logs --tail 100 --level error

Expected: No TypeError: undefined is not iterable entries.

Step 6: Verify Command Queue Stability

Send multiple rapid messages to confirm the command queue handles concurrent requests:

# Send 5 messages in rapid succession
for i in {1..5}; do
  echo "Test message $i" | openclaw send --channel test-channel
done

All messages should be processed without crashes.

Configuration Corruption

• Duplicate/nested config: Manually editing config.yml can introduce nested copies. Always use openclaw config set for programmatic updates.
• YAML indentation: Incorrect indentation breaks parsing. Use spaces (not tabs) for indentation.
• Special characters: Unquoted strings containing :, #, {, } can cause parse errors.

Plugin Management

• Plugin not in allow list: Even if installed, a plugin will not load unless explicitly listed in plugins.allow.
• Removed plugins: Plugins removed in prior versions (like browser) may persist in config and cause validation failures.
• Order sensitivity: Some plugins have dependencies. Ensure dependent plugins are declared after their dependencies.

Version-Specific Traps

• Skipping versions: Upgrading directly from 4.3 to 4.5 may miss migration steps. Use sequential upgrades for complex version jumps.
• Lock file drift: package-lock.json may cache the broken version. Delete lock file before reinstalling.

Environment-Specific Issues

• Docker: Ensure volume mounts persist config between container restarts. Check that openclaw doctor --fix writes to the correct mounted volume.
• pm2/systemd: Service managers may cache old process state. Restart the service, not just the process.
• Windows: Line ending differences (\r\n vs \n) can corrupt YAML. Ensure consistent line endings in config.yml.

Migration Gotchas

• Channel allow keys: Version 4.5 removed per-channel allow rules. Migrate any existing rules to the new permission system before upgrading.
• Plugin config keys: Some plugin-specific keys were renamed. Check the 4.5 changelog for deprecated key mappings.