Skip to content

Troubleshooting

Jump to bottom
Emiel Kollof edited this page Apr 3, 2026 · 3 revisions

Troubleshooting

First steps

Before reporting a bug, check the WeeChat core log and the plugin's own log:

/debug dump           # write full WeeChat state to ~/.local/share/weechat/weechat.log
/set xmpp.look.debug_level 2   # increase verbosity
/save

Reconnect your account; verbose output will now appear in the plugin buffer. Reset with /set xmpp.look.debug_level 0 when done.

Log files

File Contents
~/.local/share/weechat/logs/xmpp.account.<name>.weechatlog Per-account plugin log
~/.local/share/weechat/xmpp/raw_xml_<name>.log Raw XMPP XML stream
~/.local/share/weechat/weechat.log WeeChat core log

Read the last 200 lines of the account log:

tail -200 ~/.local/share/weechat/logs/xmpp.account.myaccount.weechatlog

Search for OMEMO-related events:

grep -i "omemo\|bundle\|devicelist" \
    ~/.local/share/weechat/logs/xmpp.account.myaccount.weechatlog

Correlating OMEMO events with raw XML

For OMEMO key-transport or session-bootstrap issues, use the correlation helper:

tools/correlate_omemo_xml.sh --account <name>

This cross-references WeeChat log events with timestamps from the raw XML log so you can see exactly which stanzas triggered which log lines.

Common problems

Plugin fails to load

Symptom: /plugin load xmpp.so shows an error or the plugin is not listed.

Checks:

  1. Verify the build succeeded: make should print no errors.
  2. Check that xmpp.so ended up in ~/.local/share/weechat/plugins/.
  3. Confirm WeeChat can find it: the path must match what WeeChat scans — check with /set weechat.plugin.path.
  4. Ensure all runtime libraries are installed (ldd xmpp.so should show no missing libraries).

Cannot connect to XMPP server

Symptom: /account connect hangs or immediately disconnects.

Checks:

  1. Verify DNS resolves for your server and that port 5222 (or 5223 for TLS) is reachable.
  2. Check credentials: JID and password are correct.
  3. Look in the raw XML log for <failure> stanzas or TLS errors.
  4. Some servers require explicit TLS; try both user@domain and user@domain/resource.

MUC nick shows as full JID

Symptom: Messages in a MUC room display room@conf.server/nick instead of just nick.

This is a known issue that was fixed in commit 253f987. Make sure you are running an up-to-date build:

git pull && make clean && make && make install

Then restart WeeChat (plugin reload in-place is not supported).

PM buffer reappears after /close

Symptom: A direct-message buffer you closed with /close comes back automatically on the next connect or when the contact sends a message.

Cause: An old MAM cache entry or a presence handler auto-creating the buffer.

Fix: This was resolved in earlier commits. Ensure you are on a recent build. If the problem persists, clear the LMDB cache for the account:

rm -rf ~/.local/share/weechat/xmpp/<account>.db

Then restart WeeChat. A fresh MAM sync will rebuild the cache without the stale sentinel.

Typing indicator shows full JID instead of nick

Symptom: The typing bar shows room@conference.server/nick instead of nick.

This was fixed alongside the MUC nick display bug. Update to the latest build and restart WeeChat.

OMEMO: pre-key exhaustion after signed pre-key rotation

Symptom: After some time, new sessions fail with "no pre-key" errors or the bundle appears to contain the same pre-keys as before.

Cause (fixed): A previous bug caused ensure_prekeys to regenerate all 100 pre-keys starting from ID=1 after each signed pre-key rotation, silently reusing IDs that remote devices had already consumed. This caused session establishment failures and silent decryption errors for devices that tried to use a "fresh" pre-key that had already been used to build an earlier session.

Fix: Pre-key ID continuity is now enforced — the maximum allocated pre-key ID is persisted in LMDB and new batches always start from max_id + 1, matching Signal protocol requirements. If you experienced this issue, run:

/omemo republish
/omemo reset-keys     # WARNING: clears all sessions; only if sessions are broken

OMEMO: self-message or carbon-copy not decrypting

Symptom: Messages you send do not appear in plaintext on your other devices, or a message sent to yourself shows as encrypted.

Cause (fixed): A guard condition previously skipped encrypting for your own device when the sender and recipient JID were the same (self-message), and also skipped including the sender's current device in multi-device sends. This meant carbon copies received on other own devices could not be decrypted.

Fix: The own-device block is now always included in every encrypted message, matching Profanity's reference implementation. No user action required; the fix is active after rebuilding.

Symptom: The plugin repeatedly prints no key for our device for a contact.

This is usually a key-transport bootstrap issue — the remote device has not yet received your key. The plugin suppresses repeated messages once bootstrap is pending. If it persists:

/omemo republish          # republish your bundle nodes
/omemo kex <jid>          # force key transport to all devices of that JID

If the problem continues, reset and renegotiate:

/omemo reset-keys         # WARNING: clears all sessions
/omemo                    # re-enable OMEMO

OMEMO: messages not decrypting

Symptom: Received messages show as encrypted (no plaintext body).

  1. Check that OMEMO is enabled: the status bar item should show OMEMO.
  2. Run /omemo status to confirm your device ID and that your bundle is published.
  3. Use the OMEMO correlation helper to see which key-transport stanzas were received: 
    tools/correlate_omemo_xml.sh --account <name>
  4. Try /omemo fetch <jid> to force a fresh devicelist and bundle fetch.

make fails: invalid conversion from 'int' to 'const char*'

You are building against WeeChat < 4.3.0. Edit src/omemo.cpp and change:

#if 1  // Set to 0 for WeeChat < 4.3.0

to:

#if 0

Then make clean && make.

make fails with missing headers

Run make install-deps to install system packages, or install the libraries listed in Installation manually.

Plugin reload causes issues

Do not use /plugin reload xmpp — this triggers race conditions with timer hooks. Always close and reopen WeeChat after rebuilding:

make && make install
# close WeeChat, then reopen it

Enabling raw XML logging

Raw XML is written to ~/.local/share/weechat/xmpp/raw_xml_<account>.log automatically. No extra configuration is required; the file is created when the account connects and appended to on each run.

To watch it live while WeeChat is running:

tail -f ~/.local/share/weechat/xmpp/raw_xml_myaccount.log

Reporting a bug

Please open an issue at github.com/ekollof/xepher/issues and include:

  • WeeChat version (/version)
  • Plugin version (shown by /xmpp)
  • Distribution and compiler version (g++ --version)
  • Relevant lines from the account log and/or raw XML log
  • Steps to reproduce

Clone this wiki locally