Troubleshooting on Margrop Blog

Stop Installing Another PC Cleaner: What Desktop Software Can an AI Agent Actually Replace?

Sun, 19 Jul 2026 22:00:00 +0800

The short answer

An AI Agent can replace many desktop utilities whose main job is clicking the same buttons over and over. It does not turn every application into a chat box, and it is not a magical “computer doctor.” Its real advantage is orchestration: it can inspect the machine, understand the goal, combine built-in tools, execute a sequence, and explain the evidence.

Across five categories—file conversion, junk scanning, performance optimization, configuration changes, and computer repair—the replacement level is different. File conversion and reporting are highly automatable. Performance work and configuration changes are semi-automatic. Hardware repair remains a human job, with the Agent acting as a diagnostic assistant.

The safety rule for every script in this article is simple: read first, write second; back up first, change second; verify before claiming success. All three scripts are local-only and start in report mode. Destructive actions require an explicit flag and a second confirmation.

Docker Container Crash Loop After v3.7.0? You're Missing One Word: serve

Thu, 02 Jul 2026 19:30:00 +0800

TL;DR

After upgrading Siyuan (SiYuan Note) from v3.6.x to v3.7.0, the Docker container entered an infinite restart loop. docker logs showed Error: unknown flag: --accessAuthCode. The root cause: v3.7.0 introduced a CLI subcommand architecture. The old top-level flags now require a serve subcommand. The fix is adding one word — 'serve' — to the beginning of the command array in docker-compose.yml. Seven characters. From crash loop to running.

This article covers the complete troubleshooting process, one-command fix scripts for Windows 11, Ubuntu 26.04, and macOS 26, plus both manual and AI Agent approaches. All scripts use only Docker CLI and SSH — no third-party services required.

One sentence let Claude upgrade Ubuntu 22.04 to 24.04: a near-zero-screen-time cross-LTS run

Fri, 19 Jun 2026 10:58:00 +0800

TL;DR

A remote home-lab box had been sitting on Ubuntu 22.04.4 LTS (jammy, kernel 5.15) for a long time. After one sentence — “upgrade the box at 192.168.103.182 to Ubuntu 24.04” — Claude opened a tmux session to babysit the run, brought up a fallback sshd on port 1022 so a mid-upgrade sshd restart would not strand me, then drove do-release-upgrade -f DistUpgradeViewNonInteractive end to end. Twenty-five minutes later the host came back: kernel 6.8.0-124, every service still listening.

This is not a tutorial on do-release-upgrade; the Ubuntu docs already cover that. This is about what an Agent does once it gets an SSH handle on a box, why it does each step, and which pitfalls you have to clear out of the way before letting it loose.

Ubuntu shutdown stuck for 90 seconds? A Python asyncio service that won't honour SIGTERM, and how to fix it

Fri, 19 Jun 2026 10:58:00 +0800

TL;DR

After upgrading my home proxy box to Ubuntu 24.04, systemctl reboot stopped being fast: SSH would hang on for 90 seconds before the box actually shut down. journalctl made it obvious: smart-proxy.service: State 'stop-sigterm' timed out. Killing. — systemd sent SIGTERM, waited 90 seconds, nobody reacted, and SIGKILL was the only option left.

The root cause is not systemd’s fault and not Ubuntu’s fault. It is Python’s asyncio runtime not actually ending its child tasks when SIGTERM arrives — it is parked on a socket.recv and never voluntarily looks at the signal queue.

The fix has two halves, both required: (1) a systemd drop-in that lowers TimeoutStopSec from the default 90s down to 20s on the affected Python units; (2) inside the Python service itself, walk asyncio.all_tasks(), .cancel() the in-flight connection handlers on SIGTERM, and wrap self.stop() in asyncio.wait_for(..., timeout=10) as a safety net. After both halves, the same reboot drops from 90 seconds to one second.

I dockerized AnythingLLM and the container turned into a wound-up squirrel — restarting forever until I handed it that magic 1000:1000

Wed, 17 Jun 2026 20:30:00 +0800

TL;DR

AnythingLLM, Mintplex Labs’ “stuff-anything-in-a-LLM” desktop, ships an official Docker image. In the happy path one docker run is all you need. But the in-container user anythingllm is picky: the host directory you bind-mount has to be owned by 1000:1000, otherwise it can’t write its own SQLite file, the Prisma migration step on startup crashes, and the container enters a restart-crash-restart loop. The fix takes under a minute: chown -R 1000:1000 /your/data/dir, then docker compose up -d again, and it dutifully listens on 3001.

I’ll also explain why Prisma’s file:../storage/anythingllm.db relative path is a footgun, give you a Portainer-ready stack file, and finish with a Q&A on the most common gotchas.

PhotoPrism Stuck for 5 Minutes on First Boot? A Postmortem on PHOTOPRISM_INIT=intel

Sat, 13 Jun 2026 08:30:00 +0800

TL;DR (The Short Version)

The PHOTOPRISM_INIT: "intel" line in PhotoPrism’s Plus Docker image is not just a flag to enable Intel hardware acceleration at runtime — it’s a one-shot system-level installer that runs apt-get dist-upgrade against archive.ubuntu.com and then installs 8 Intel/VA-API packages before the main process is allowed to start. On a fresh container this takes 5–10 minutes (sometimes more), during which nothing inside the container listens on port 2342.

Meanwhile: docker ps says Up, Portainer is green, ss -ltn on the host shows :2342 LISTEN — but your browser gets ERR_CONNECTION_RESET / Connection reset by peer. Because host-side docker-proxy accepts the connection and then tries to forward to a port inside the container that has no listener, the kernel sends back an RST.

Fix: just remove or empty that one line. If you already pass /dev/dri/renderD128 via devices:, the host’s drivers and userland libraries are perfectly usable from the container — there’s nothing to “install” in there.

The Portainer 500 Error That Wasn't the YAML — A Two-librespeed_default-Network Story

Sat, 13 Jun 2026 08:00:00 +0800

The short version

You update a stack in Portainer. The browser slaps you with a red 500 Internal Server Error. You assume the YAML is wrong, fix the indentation, swap the quotes, drop the image tag. You hit Update again. Same 500. And again. And again.

The real culprit is buried at the deepest level of the HTTP response body: network librespeed_default is ambiguous (2 matches found on name). Two networks with the same name exist in the same Docker engine—two IDs, two Created timestamps, two com.docker.compose.config-hash labels, but a single shared name. Compose asks the engine to look up that name; the engine refuses to pick between them; compose up fails; Portainer wraps the error as a 500 and returns it to your browser.

The fix is embarrassingly simple: delete one of the two orphan networks (docker network rm <id> or click Remove in Portainer’s Networks page), then re-run Update the stack with the exact same content. It just works.

This post is a real debugging session: a stack update that was supposed to be a 30-second mount-path change turned into a 1-hour investigation. All private details (internal addresses, registry URLs, volume paths, container names, credentials) have been replaced with <PLACEHOLDER>. Only public source code, official docs, and the error text itself are preserved.

The Docker Container Is Running, the Port Is Dead: A Complete Walkthrough of a Silent Host-Bind Failure

Sat, 13 Jun 2026 07:30:00 +0800

TL;DR:

docker ps says everything is fine. docker inspect’s HostConfig.PortBindings clearly says 203.0.113.14:3001:3000. But on the host, no docker-proxy is listening, the iptables nat/DOCKER chain has no DNAT rule, and NetworkSettings.Networks and Ports are both empty {}. This “container alive, port dead” state is what happens when libnetwork silently rolls back the endpoint creation because the target interface wasn’t up at attach time — and Docker doesn’t bother to tell you that the port publish never actually happened. The fix is a single 30-second command: docker network connect <net> <ctr>.

From 5m14s to 0.6s: How I Rebuilt My Docker Hub Mirror After Hitting Three Walls

Sat, 13 Jun 2026 07:20:00 +0800

TL;DR

My home lab had a registry:2 pull-through cache fronting Docker Hub for years, and it was fine. Then one day pulling a 5 MB alpine:3.19 took 5 minutes and 14 seconds. This post is the full forensic log of how I traced the slowdown, evaluated 8 candidate mirrors with real measurements (not vibes), and finished with a 5-line bash script on cron that auto-fails-over when the primary mirror goes down. Every number in this article was captured on my own hardware, in my own network, at one specific moment in time.

If you also self-host a Docker Hub mirror, or your team runs an internal registry, the Q&A at the bottom will probably save you 3 hours of pain.

OpenClaw TUI Keeps Repeating Itself? A Temporary Patch for Duplicate Thinking and Replies

Tue, 02 Jun 2026 10:42:00 +0800

The short version

If OpenClaw TUI shows the same thinking block twice and repeats the final answer, do not immediately delete every session or rebuild every model provider. In many OpenAI-compatible setups, the real issue is a streaming compatibility edge case: the upstream stream emits normal delta chunks and then an extra full message tail. Some OpenClaw paths may aggregate both, so the TUI and the persisted session both end up with duplicated content.

The practical temporary fix is to back up the local OpenClaw installation, add a conservative dedupe guard in the OpenClaw aggregation layer, restart the gateway, and verify with a unique marker that both the visible reply and the session file contain only one copy.

This is a privacy-safe incident note. All endpoints, model names, tokens, internal addresses, and session identifiers are replaced by placeholders. Use your own installation path and model identifiers when applying the workaround.

VPN Connected, But Internal Hostnames Won't Resolve? A Complete macOS Routing Table Walkthrough

Mon, 01 Jun 2026 18:00:00 +0800

TL;DR:

When two VPNs run side-by-side on macOS (e.g. utun0 and utun15), an aggregate 10.0.0.0/8 route pushed by one of them can silently “swallow” every address in the 10.x.x.x range — including the one you actually wanted to reach on the other VPN. DNS resolves fine; TCP/ICMP just hangs. route -n get is the first knife you should reach for.

Your Mac App Is Not Broken: Gatekeeper May Just Distrust an Unsigned Tool

Mon, 01 Jun 2026 07:35:00 +0800

The short version

When a macOS utility refuses to launch after being downloaded, the first conclusion should not be “the app is broken.” A very common cause is a combination of two facts: the app still has the com.apple.quarantine extended attribute that marks it as downloaded from the internet, and the app bundle does not have a usable signature that Gatekeeper can trust. For first launch, “downloaded from the web + no usable signature” is enough for macOS to block it.

For a tool whose source you understand and trust, the smallest local repair is straightforward: inspect the quarantine attribute, verify the signing state, apply a local ad-hoc signature to that one app bundle, remove quarantine from that one app, and then verify the result. The point is not to turn off macOS security globally. The point is to fix one known local tool while keeping the safety boundary clear.

This post is based on a real local troubleshooting session, but all private details have been removed. There are no real internal addresses, usernames, tokens, private download locations, hostnames, or machine-specific paths. The examples use placeholders such as /Applications/<App>.app and <App>. The goal is to share a repeatable diagnostic method, not to expose an environment.

Your Background Process Keeps Dying After Shell Exit? Stop Blaming nohup — Understand setsid and Unix Process Lifecycle

Mon, 01 Jun 2026 07:00:00 +0800

The short version

You launched a background service. You used nohup. You added &. You redirected output. Everything looked fine. But when you closed the terminal, disconnected SSH, or—more insidiously—when an automation tool finished executing its script, the process silently vanished. You checked ps—nothing. You checked the port—nothing. No error in the logs. If this has happened to you, you’re not alone.

The root cause isn’t SIGHUP—at least, not entirely. The real issue is process group and session membership. nohup merely tells the process to ignore the SIGHUP signal, but the process still belongs to the same session and process group as the parent shell. When the shell exits and sends SIGHUP to the entire process group, nohup helps—but only if the signal delivery chain stops there. If the controlling terminal is destroyed, if stdin/stdout pipes break, or if the parent’s process group is collectively reaped, the process can still die. The proper fix is setsid: it creates a brand-new session, detaches from the controlling terminal, and places the process in its own process group—so SIGHUP from the parent shell never reaches it in the first place.

This post is based on a real debugging session of the CLIProxyAPI service. The service was started with nohup but kept disappearing every time an automation script finished. The management panel kept showing “connection failed.” The culprit turned out to be a subtle Unix process lifecycle issue. This class of problem is common in cloud dev machines, CI runners, SSH jump hosts, and containerized workflows, but it’s often misdiagnosed because the underlying process model is poorly understood.

All private details have been removed. No real internal addresses, tokens, or paths appear in this article.

You Can SSH Out, but Not Back In: A Fail2Ban False Positive That Broke Reverse Access

Sat, 30 May 2026 15:45:00 +0800

Bottom line

The symptom looked simple: I could SSH from the local machine into a remote internal host, but the reverse SSH path failed when the remote host tried to connect back. sshd was listening, the route table looked fine, and the failure still happened.

The real root cause was not a broken SSH daemon. Fail2Ban had banned the VPN gateway address that represented the return path. From the local machine’s point of view, the incoming SSH session did not appear to come directly from the remote host. It appeared to come from the gateway, so the ban cut off the whole reverse path.

Claude Code Upgrade Broke Every Model? Before You Rotate Keys, Check the Compatibility Gateway

Fri, 29 May 2026 15:30:00 +0800

The short version

After a Claude Code upgrade, every model call failed with the same error: API Error: 400 invalid params, chat content has invalid message role: system (2013). At first glance this looks like a bad API key, a dead model, an exhausted account, a broken proxy, or a provider-wide outage. The root cause was different: a newer Claude Code request shape crossed an Anthropic-compatible model gateway that had not caught up with the client-side protocol behavior. The gateway, or a downstream chat validation layer behind it, rejected a system role in a place where it did not expect one.

The practical fix was not to randomly reinstall things. I reproduced the failure with the smallest possible prompt, tested adjacent Claude Code versions, and found the last known good version. 2.1.150 returned OK; 2.1.154 and 2.1.156 reproduced the 400. Pinning the global Claude Code installation back to 2.1.150 restored the existing provider path.

This post is a troubleshooting write-up for a local Claude Code environment. The fix itself was small, but the incident is useful because it shows a pattern that is becoming common in AI agent tooling: the CLI, environment settings, model gateway, API compatibility layer, and actual model backend are often separate moving pieces. When one layer changes its request structure, the terminal may only show a vague 400.

All private details have been removed. This article does not include real internal addresses, usernames, tokens, private provider names, local absolute paths, or private service domains. Configuration examples use placeholders such as <PLACEHOLDER>, <MODEL_GATEWAY>, and <MODEL_NAME>. The goal is to document a reusable debugging method, not to expose a specific environment.

Avoiding the Trap: Why Fail2Ban Fails on Ubuntu 26.04 & PVE 9.2 (And How to Fix It)

Tue, 26 May 2026 22:20:00 +0800

The Bottom Line

With the releases of Ubuntu 26.04 LTS and Proxmox VE (PVE) 9.2, many system administrators, DevOps engineers, and self-hosting enthusiasts have eagerly upgraded or clean-installed these latest systems. However, during the post-installation security hardening phase, you may encounter a highly frustrating scenario: simply copying over your legacy Fail2Ban configuration files from older versions (such as Ubuntu 20.04/22.04 or PVE 7.x/8.x) will either cause the Fail2Ban service to crash during startup or, worse, run silently in the background while completely failing to block external brute-force attacks!

This issue is not caused by a bug in Fail2Ban itself. Instead, it is the result of three “invisible bombs” hidden beneath the surface of these modern Linux distributions, namely changes in the logging architecture, service activation mechanisms, and firewall backends. This article provides an in-depth analysis of these three architectural shifts and introduces a modern, bulletproof Fail2Ban configuration guide fully integrated with systemd-journald and nftables.

Don't Rush After Installing Ubuntu 26.04 LTS! Swiftly Configure Domestic Mirrors (Huawei & Alibaba Cloud APT Sources DEB822 Tutorial)

Tue, 26 May 2026 21:00:00 +0800

TL;DR

Ubuntu 26.04 LTS (Resolute Raccoon) has officially been released. If you have just installed it, the very first thing you should do is replace the default APT sources with fast domestic mirror servers (such as Alibaba Cloud or Huawei Cloud). Note that starting from Ubuntu 24.04, the system has transitioned entirely to the new DEB822 format for APT source configurations (stored in /etc/apt/sources.list.d/ubuntu.sources), making the traditional /etc/apt/sources.list inactive by default.

This tutorial provides a step-by-step guide on how to safely change to Alibaba Cloud and Huawei Cloud mirrors in Ubuntu 26.04 LTS, along with deep troubleshooting analysis for potential pitfalls like dependency conflicts and version codename mismatches.

Your MCP Config Was Fine. The Server Died Before the Handshake.

Sat, 23 May 2026 06:10:00 +0800

The short version

The misleading part of this incident was the surface error. Codex reported that an MCP client could not initialize and that the MCP server handshake failed. That naturally pushes you toward MCP configuration, JSON-RPC initialization, plugin settings, authentication, network transport, or stale tool caches. But the root cause was lower than the MCP protocol: one local MCP server binary was killed by the macOS dynamic linker before it could answer the initialize request. The client only saw a closed connection. The useful evidence was in the server stderr: dyld: Symbol not found, pointing at a missing Swift Concurrency runtime symbol.

In other words, MCP did not really get a chance to fail. The server process died first.

This article walks through a real troubleshooting pattern around Codex, MCP clients, and MCP servers. The failure looked like a protocol startup problem, but the root cause lived in a native macOS binary and its Swift runtime compatibility.

All private details have been removed. This article does not include real internal addresses, usernames, session IDs, full local paths, tokens, private repository names, or business system names. Paths use placeholders such as ~, <USER_HOME>, <PLUGIN_DIR>, and <PROJECT>. Log snippets keep only the technical fields needed to explain the diagnosis.

New Chrome Could Not Log In to Bitwarden, but Old Machines Still Worked: A Vaultwarden Compatibility Trap

Mon, 18 May 2026 10:05:00 +0800

TL;DR

The failure looked like a Chrome or Bitwarden extension problem: newly installed computers could not log in to a self-hosted Vaultwarden instance, while existing computers continued to work with the same Bitwarden 2026.4.1 browser extension. The actual root cause was server-side compatibility: the clients were using a newer prelogin endpoint, while the Vaultwarden server was still running vaultwarden/server:1.35.4-alpine, which did not provide /identity/accounts/prelogin/password.

Existing machines were likely protected by an already established login state and local cache. They did not prove that the full first-login API path was still compatible. The correct fix was to back up the Vaultwarden data, upgrade the server image to 1.36.0 or newer, and confirm from logs that the prelogin endpoint no longer returned 404.

All domains, paths, usernames, and deployment details in this article are sanitized. Examples use placeholders such as vault.example.com and /opt/vaultwarden; no internal network or private information is included.

[Clickbait Alert] Switching to a Chinese Mirror Nearly Broke My Ubuntu: A Real Story of apt Dependency Hell

Sun, 17 May 2026 10:00:00 +0800

TL;DR

I switched to a domestic Chinese mirror for Ubuntu and thought it would take 10 minutes. It took two hours. This article documents the entire journey from “mirror sync delay causing version mismatch” to “dpkg forced downgrade” to “apt fully restored.” The core lesson: switching a mirror is not a one-click fix—version consistency is everything. If you swap mirrors on a system that’s been running for months, you have a 99% chance of hitting dependency conflicts.

All operations in this article are based on Ubuntu 26.04 (Plucky). All IPs, hostnames, and paths are sanitized examples and contain no internal network addresses or sensitive information.

Debugging Chinese Text Turning into Underscores in tmux + opencode: The Real Culprit Was client_utf8=0

Tue, 28 Apr 2026 18:40:00 +0800

Short version

This was not an opencode Chinese rendering bug, and it was not a broken terminal font. The tmux client had been detected as not supporting UTF-8. The decisive evidence was tmux display-message -p 'client_utf8=#{client_utf8}', which returned client_utf8=0. In that state, tmux replaces non-ASCII output with underscores, so every Chinese character inside the opencode TUI appeared as _.

This post documents a small but very typical terminal debugging session. On the same Mac, running opencode directly displayed Chinese text correctly. But after starting a tmux session first and then running opencode, all Chinese text became underscores.

This kind of problem is easy to misdiagnose. The first instinct is often to blame the font, the terminal emulator, the opencode version, a color theme, Nerd Font configuration, Unicode width handling, or a bug in the TUI framework. In this case, however, the key question was much narrower: does the current tmux client believe it can write UTF-8 back to the outer terminal?

To avoid exposing private environment details, all examples below are generalized. They do not include real hostnames, private addresses, session names, credentials, usernames, or project paths. The only things preserved are the technical facts needed to understand the failure and the fix.

OpenClaw Backup Failure Investigation and Fix: From Two Broken Schedules to a Fully Restored Automation Pipeline

Mon, 13 Apr 2026 09:30:00 +0800

This post is a full incident review, not because the failure was dramatic, but because it was a very typical automation problem.

Two machines lost their automatic OpenClaw backups at the same time: a local macOS machine and a remote VPS. Manual runs worked on both sides, and the archives could still be synchronized to the NAS, but the scheduled jobs were unreliable. At first glance it looked like “the scheduler did not fire.” In reality, the root cause was spread across scheduling, permissions, locking, logging, and even the way I validated the schedule.

That combination is what makes these incidents annoying: every individual piece looks almost fine, yet the full pipeline still fails.

Upgrading OpenClaw to 2026.3.23-2: A Real Compatibility Upgrade Playbook

Tue, 24 Mar 2026 21:20:00 +0800

This post documents a real OpenClaw upgrade, not a laboratory demo. The goal was not simply to change a version string. The real goal was to move a small multi-node environment from 2026.3.8 / 2026.3.13 to 2026.3.23-2 while keeping message channels, external plugins, service startup behavior, and rollback paths under control.

In practice, the most difficult part was not the OpenClaw core package. The hardest part was everything around it: plugin SDK compatibility, JIT cache reuse, mixed installation layouts, restricted outbound access on an edge node, and differences in bind mode that changed what health probes actually meant. If you do not identify those variables first, an upgrade can easily look successful while one or more production channels are already broken.