Document "No adapter for channel type" duplicate-service issue

advanced/troubleshooting.mdx

@@ -111,6 +111,74 @@
   ```
 </Accordion>
 
+## Messages silently lost ("No adapter for channel type")
+
+### Symptoms
+- The bot stops replying even though messages appear to be received and processed.
+- `logs/nanoclaw.error.log` contains repeated entries like:
+  ```
+  WARN No adapter for channel type channelType="telegram"
+  WARN No adapter for channel type channelType="signal"
+  ```
+- The main log shows "Message delivered" entries with `platformMsgId=undefined`. The delivery poll ran, found no adapter, and permanently marked the message as delivered without sending it.
+
+### Root cause
+
+Two NanoClaw service instances are running simultaneously. A second instance (often `nanoclaw-v2-<id>.service` running alongside `nanoclaw.service`) starts with a stale binary that has no channel adapters registered. Its delivery poll races against the working instance and wins — permanently marking outbound messages as delivered without ever sending them.
+
+Affected messages cannot be retried because they have a null `platform_message_id`. The user must resend their message after the duplicate is removed.
+
+### Diagnosis
+
+```bash
+# Check for duplicate running instances
+ps aux | grep 'nanoclaw/dist/index.js' | grep -v grep
+
+# Check which user services are active
+systemctl --user list-units 'nanoclaw*' --all
+
+# Confirm channel adapters registered by the current process
+grep "Channel adapter started" logs/nanoclaw.log | tail -10
+```
+
+### Solutions
+
+<Steps>
+  <Step title="Identify the correct service">
+    The correct service is the one whose log shows all expected channel adapters started (e.g., `signal`, `telegram`, `cli`). The stale instance will be missing these.
+  </Step>
+
+  <Step title="Stop and disable the stale duplicate">
+    ```bash
+    systemctl --user stop nanoclaw.service       # or whichever is the old one
+    systemctl --user disable nanoclaw.service
+    ```
+  </Step>
+
+  <Step title="Ensure the surviving service has its environment file">
+    If the remaining unit is missing `EnvironmentFile`, add it under `[Service]`:
+
+    ```ini
+    EnvironmentFile=/home/<user>/nanoclaw/.env
+    ```
+
+    Then reload and restart:
+
+    ```bash
+    systemctl --user daemon-reload
+    systemctl --user restart nanoclaw-v2-<id>.service
+    ```
+  </Step>
+
+  <Step title="Verify only one instance runs">
+    ```bash
+    ps aux | grep nanoclaw/dist/index.js | grep -v grep
+    ```
+
+    You should see exactly one process.
+  </Step>
+</Steps>
+
 ## Container timeout
 
 ### Symptoms
@@ -189,7 +257,7 @@
 
 ### Cause
 
 By default, systemd sets `Linger=no` for users. When your last SSH session closes, systemd terminates all user-level processes — including the NanoClaw service. This is especially common on cloud VMs (EC2, GCP, Oracle Cloud).
 
 ### Solution
 
@@ -207,7 +275,7 @@
 ```
 
 <Note>
   If `loginctl enable-linger` fails with a permission error, your system may require polkit authorization. Contact your system administrator or run the command with `sudo`.
 </Note>
 
 ## Known issues
@@ -233,7 +301,7 @@
 
 **Symptoms:** `Container exited with code 125: pull access denied for nanoclaw-agent` — the container image disappears after a few hours, even though you just built it.
 
 **Cause:** If your container runtime has Kubernetes enabled (Rancher Desktop enables it by default), the kubelet runs image garbage collection when disk usage exceeds 85%. NanoClaw containers are ephemeral (run and exit), so `nanoclaw-agent:latest` is never protected by a running container. The kubelet sees it as unused and deletes it — often overnight when no messages are being processed.
 
 **Fix:** Disable Kubernetes if you don't need it:
 
@@ -256,7 +324,7 @@
 grep -E "image found|image NOT found|image missing" logs/nanoclaw.log
 ```
 
 If you need Kubernetes enabled, set `CONTAINER_IMAGE` to an image stored in a registry that the kubelet won't garbage-collect, or raise the kubelet's GC thresholds.
 
 ### Resume branches from stale tree position
 
@@ -304,7 +372,7 @@
 
 <CodeGroup>
 ```bash macOS
 launchctl kickstart -k gui/$(id -u)/com.nanoclaw
 ```
 
 ```bash Linux
@@ -346,7 +414,7 @@
 
 <CodeGroup>
 ```bash macOS
 launchctl kickstart -k gui/$(id -u)/com.nanoclaw
 ```
 
 ```bash Linux
@@ -393,21 +461,21 @@
   }
   ```
 
   Then restart the service. If the mount allowlist file did not exist at startup, NanoClaw will detect it once created without requiring a restart.
 </Accordion>
 
 <Accordion title="Reset mount allowlist to defaults">
   If you need to regenerate the default mount allowlist (for example, after a misconfiguration), re-run setup with the `--force` flag:
 
   ```bash
   claude /setup --force
   ```
 
   Without `--force`, setup skips the mount allowlist if it already exists to preserve your customizations.
 </Accordion>
 
 <Accordion title="Check for symlinks">
   The mount security system resolves symlinks before validation. If you're mounting a symlink, ensure the resolved path is in the allowlist:
 
   ```bash
   readlink -f /path/to/symlink
@@ -415,7 +483,7 @@
 </Accordion>
 
 <Accordion title="Verify file permissions">
   Containers run as the host user (or uid 1000 on some systems). Ensure the host user can read the mounted directories:
 
   ```bash
   ls -la /path/to/mount
@@ -493,7 +561,7 @@
 
 | Artifact | Retention | Notes |
 |----------|-----------|-------|
 | Session JSONLs and tool results | 7 days | Active sessions (from DB) are never deleted |
 | Debug logs | 3 days | Active sessions skipped |
 | Todo files | 3 days | Active sessions skipped |
 | Telemetry | 7 days | Active sessions skipped |
@@ -509,7 +577,7 @@
 
 ## Stale session auto-recovery
 
 NanoClaw automatically detects and recovers from stale or corrupt sessions. When a container fails because the session transcript file (`.jsonl`) is missing — due to a crash mid-write, manual deletion, or disk-full condition — NanoClaw clears the broken session ID and lets the existing backoff mechanism in the group queue retry with a fresh session.
 
 Stale sessions are detected by matching the error output against known patterns (`no conversation found`, `ENOENT` on `.jsonl` files, or `session not found`). Only these specific signals trigger session clearing — transient errors (network, API) fall through to the normal retry path.