Backup on Lessons learned

Backing up ~/.claude and ~/.codex without archiving your AI logins

Sat, 31 Oct 2026 22:29:00 +0100

If you back up the whole ~/.claude or ~/.codex folder, the restore works, and the backup now holds everything an infostealer wants. The same folder holds your settings, every session transcript in plaintext, and, on Linux, the login itself:

~/.claude/.credentials.json # Claude Code login, mode 0600
~/.codex/auth.json # Codex login when file storage is in use
~/.claude/projects/*/*.jsonl # transcripts: prompts, tool output, file contents

Split the folder into two lists. Back up what you wrote: settings, instructions, skills, hooks, and memory. Keep transcripts as optional encrypted data. Leave login files out of routine backups and log in again after a restore.

Where AI client state lives on macOS and Linux

I checked these paths against Claude Code 2.1.316, Claude Desktop for Linux 4.4212.0, ChatGPT for macOS 1.2026.183, the Codex desktop app for macOS 26.1027.30824, and Codex source at commit 67f0994. “Documented” means the vendor docs name the path. “Observed” means I found it by inspecting the official build so that it can change in any release.

Client	State root	Login material	Evidence
Claude Code	`~/.claude/` and `~/.claude.json`, both under `CLAUDE_CONFIG_DIR` if set	Keychain on macOS, or `~/.claude/.credentials.json` when the Keychain rejects the write (locked in an SSH session, for example). On Linux, always that file	Documented
Claude Desktop	macOS: `~/Library/Application Support/Claude/`. Linux (beta): `${XDG_CONFIG_HOME:-~/.config}/Claude/`	Electron cookies and Local Storage, extension secrets encrypted with `safeStorage`	MCP config documented, rest observed
ChatGPT desktop, macOS only	`~/Library/Application Support/com.openai.chat/`, `~/Library/Group Containers/2DC432GLL2.group.com.openai.chat/`, `~/Library/Preferences/com.openai.chat.plist`	Keychain items in OpenAI’s access group	Observed
Codex desktop, macOS only	`~/Library/Application Support/Codex/`, plus `~/.codex`	Shared with Codex CLI	Observed
Codex CLI	`${CODEX_HOME:-~/.codex}`. `CODEX_SQLITE_HOME`, `sqlite_home` and `log_dir` can move parts of it	`auth.json` in `file` mode or as the `auto` fallback; `.credentials.json` for MCP OAuth without a keyring	Documented and source

Desktop sessions that run Claude Code write to ~/.claude/, not to the Electron folder, so include both.

What to back up and what to leave out

Treatment	Claude Code	Codex
Back up, versioned	`settings.json`, `CLAUDE.md`, `rules/`, `skills/`, `commands/`, `agents/`, `workflows/`, `output-styles/`, `keybindings.json`, `projects/*/memory/`, `agent-memory/`, `plugins/installed_plugins.json` as a manifest	`config.toml`, `*.config.toml`, `hooks.json`, `rules/`, `skills/`, agent-role files
Back up after a secret check	`~/.claude.json` (personal MCP servers, trust decisions)	MCP `env` blocks in `config.toml`
Optional, encrypted, short retention	`projects//.jsonl`, `subagents/`, `tool-results/`, `history.jsonl`	`sessions/YYYY/MM/DD/rollout-*.jsonl`, `archived_sessions/`, `history.jsonl`
Exclude	`.credentials.json`, `file-history/`, `paste-cache/`, `debug/`, `shell-snapshots/`, `session-env/`, `backups/`	`auth.json`, `.credentials.json`, `log/`, `logs_2.sqlite`, `shell_snapshots/`, `packages/`, caches

For Claude Desktop, keep claude_desktop_config.json after checking its MCP env blocks, plus a list of installed extensions and where each came from. Reinstall extensions instead of restoring their executable caches. The ChatGPT app’s local databases are caches of a server-side account; use the account’s data export for conversations you want to keep.

Why copying the whole folder is the wrong default

Transcripts are plaintext. Anthropic’s docs say that anything passing through a tool is written to the session .jsonl, so a .env file a tool reads or a token a command prints is in there. Codex rollouts record tool activity the same way.

Your backup also keeps transcripts after the client has deleted them. Claude Code deletes transcripts after cleanupPeriodDays (default 30), but keeps sessions started, or last continued in Claude Desktop or Cowork at any age unless you set desktopSessionCleanupPeriodDays. A backup with a year of history still holds a transcript eleven months after the client deleted it.

A restore can also run code. Hooks, MCP server commands, skills, plugins, desktop extensions, and shell snapshots all execute something. If malware edited them, a full restore puts it back on the clean machine.

The Keychain protects less than it seems to. It stops someone who copies the disk offline, but malware running as your user can still request the item. The Linux desktop build can also fall back to Chromium’s basic password store when no wallet is running.

Dead ends worth skipping

Guessing Linux paths from macOS ones. Replacing Library/Application Support with .config works for Claude Desktop, which has a Linux beta. OpenAI ships no Linux desktop app for ChatGPT or Codex. The Codex source has Linux branches, but there is no supported Linux build. On Linux, your ChatGPT state lives in the browser profile.
Copying only the .sqlite files. Codex keeps state in state_5.sqlite, thread_history_1.sqlite, memories_1.sqlite and others . A live copy without the -wal and -shm sidecars can be incomplete or corrupt. Stop the client and copy all three.
Treating the desktop database as the archive. The Codex desktop app can rebuild its index from the rollout JSONL files, but metadata that lives only in the database is lost, back up the JSONL files.
Assuming claude purge cleaned everything. It doesn’t touch shell-snapshots/, backups/ (older copies of ~/.claude.json) or files written by /heapdump. According to Anthropic, a heap snapshot contains the full conversation and any credentials the process held.

Restore into a staging profile

Reinstall the signed apps, plugins, and extensions from their sources.
Restore your config, then read every hook, MCP command, and executable path before the first launch.
Restore transcripts or memory only if you need them.
Log in again. Don’t restore auth.json, .credentials.json, cookies, or Keychain exports.
Resume one session and confirm that it uses the right account and repository.

Verify the backup set

To list what exists and how large it is, without printing any contents, run this on the machine you back up:

for p in "${CLAUDE_CONFIG_DIR:-$HOME/.claude}" "$HOME/.claude.json" \
 "${CODEX_HOME:-$HOME/.codex}" \
 "${XDG_CONFIG_HOME:-$HOME/.config}/Claude" \
 "$HOME/Library/Application Support/Claude" \
 "$HOME/Library/Application Support/Codex" \
 "$HOME/Library/Application Support/com.openai.chat" \
 "$HOME/Library/Group Containers/2DC432GLL2.group.com.openai.chat"; do
 [ -e "$p" ] && du -sh "$p"
done

Then check that no login file ended up in the backup:

find /path/to/mounted/backup \( -name .credentials.json -o -name auth.json \) -print

It should print nothing. If it prints anything, that backup is a credential store: encrypt it, shorten its retention, or rotate the logins.

If malware may already have run

Don’t treat a restore as the cleanup. From a clean device, revoke your Claude and ChatGPT sessions, then rotate API keys, MCP and connector credentials, and any secret that appeared in a transcript or in tool output. Any backup the malware could reach counts as exposed. Rebuild the user profile, restore only config you have reviewed, and log in again.

Caveats

Paths and retention rules change between releases. The ChatGPT and desktop paths come from build inspection, not from a published schema, so check them against your installed versions before you write a backup job. Sources: the .claude directory reference , Claude Code credential management , Codex config and state locations , Codex credential storage , Claude Desktop MCP config paths , and Electron’s app.getPath() .

Back up the config you wrote, and leave out the files the app uses for login. Run the find check above against your latest backup tonight.

'Downgrading is unsupported' after a config restore: the update guard was right

Fri, 16 Oct 2026 00:00:00 +0000

After a configuration restore, an updater refused with:

that release predates the gateway runtime these session stores now use. Downgrading is unsupported.

The operator requested an update. The restored configuration selected an older code line than the databases required. Restoring the intended per-install channel corrected target selection; bypassing the guard would have put incompatible code over newer state.

A newer release number can select older capabilities

The checkout followed a development branch. Its session databases already contained runtime-ledger history. The restored configuration backup lacked the install’s channel record, so release selection fell back to the stable channel.

The stable release had a higher patch version, but it came from a release branch without those runtime-ledger tables. Version ordering did not describe the relevant capability ordering.

The historical guard checked two things: whether the proposed target descended from the running commit, and whether a non-descendant target contained the runtime schema marker. It also read the session stores for ledger rows. Its refusal named the affected stores and stopped before moving the checkout.

The implementation explained the consequence: older code could not delete or prune sessions with that runtime history. This was a specific compatibility check, not proof that every forward commit or every future schema change would be safe.

Repair target selection before changing code

The diagnosis followed the configuration lookup:

Identify the actual install path and the channel record associated with it.
Compare that record with the backup that was restored. Check defaults when the record is absent.
Resolve the updater’s proposed target to a commit, rather than relying on its release label.
Compare the target’s ancestry and required state capabilities with the running checkout.
Reassert the intended channel through the updater’s supported configuration command, then run its check-only mode.

The corrected check selected the development branch and reported available forward commits—that verified channel selection. The update itself was deliberately not run, so the record does not establish a completed runtime upgrade.

For a Git-based installation, this read-only check is useful once TARGET is set to the exact resolved commit. Run it inside that installation’s checkout:

git merge-base --is-ancestor HEAD "${TARGET:?Set TARGET to the resolved update commit}"

Exit status 0 means the target descends from the current checkout. Status 1 means it does not; other failures require investigation. A non-descendant can be a valid release-branch target, so this command alone is not a compatibility verdict. Check the particular schema capability named by the refusal.

A config-only restore can create a mixed generation

The database kept its newer state while the restored configuration lost an additive setting. In this implementation, channel records were keyed by install path identity. Restoring an older backup, or moving an install without recreating its record, could therefore change how later updates were selected.

Deployment automation should assert the intended channel after install or restore, then read it back through the supported interface. Do not hard-code a path-derived identifier from another machine. Following a development branch is appropriate only when that is the deliberate operating policy; it is not a universal fix for update errors.

For an intentional rollback, follow the application’s documented procedure for compatible code and pre-upgrade data together. Preserve the current state first, and account for work absent from the older backup. Editing a schema-version value or removing ledger rows merely to silence the guard would discard the evidence it uses to protect the store.

Add an update-target check to your restore drill before allowing the restored installation to update itself.

Rootless Podman backup without app.ini, and a restore that fails with 'Cannot change ownership to uid 100999'

Thu, 15 Oct 2026 17:23:00 +0200

Restoring a Gitea backup to a new host failed on every directory:

tar: data/gitea: Cannot change ownership to uid 100999, gid 100999: Invalid argument
tar: data/gitea/queues: Cannot change ownership to uid 100999, gid 100999: Invalid argument

That one is easy to fix. The worse problem made no noise at all, and I found it just before: the nightly backup didn’t contain app.ini. If you back up a rootless Podman volume with a plain tar as the host user, yours may be missing files too.

The setup

Gitea 1.27 and PostgreSQL ran in rootless Podman on a VPS, with Gitea’s data in a bind mount under ~/gitea/data. The nightly backup ran as the user who owns the containers:

podman exec gitea_db_1 pg_dump -U gitea gitea | bzip2 -z9 > ~/backup/gitea-db-$(date +%y%m%d).sql.bz2
tar c -C ~/gitea/data gitea | bzip2 -z9 > ~/backup/gitea-data-$(date +%y%m%d).tar.bz2

The target was Gitea in Docker, inside an unprivileged LXC container on Debian.

The archive looked fine. It unpacked, and it contained all the repositories.

Compare the archive with the live tree

Before restoring, I compared the archive’s file list with the live data. List the live side from inside the user namespace, so that nothing is hidden from you:

ssh vps.example.com 'cd ~/gitea/data && podman unshare find gitea -type f' | sort > live.txt
tar tjf gitea-data.tar.bz2 | grep -v '/$' | sort > backup.txt
comm -23 live.txt backup.txt > missing.txt
wc -l live.txt backup.txt missing.txt

 12359 live.txt
 12342 backup.txt
 17 missing.txt

Among the 17 were the files Gitea can least do without:

gitea/gitea/conf/app.ini
gitea/gitea/jwt/private.pem
gitea/git/.ssh/authorized_keys
gitea/gitea/avatars/... (3 files)
gitea/gitea/indexers/... (4 files)
gitea/gitea/sessions/... (2 files)

app.ini holds Gitea’s SECRET_KEY, its internal tokens, and the mail settings. private.pem signs its OAuth2 tokens. A restore from this backup would have started with fresh secrets: anything encrypted with the old SECRET_KEY, such as two-factor secrets, would no longer decrypt, and the mailer would be unconfigured.

Why tar skipped them

Rootless Podman maps the container’s UIDs onto the subordinate range in /etc/subuid. With the usual entry:

deploy:100000:65536

container root is you, and container UID 1000 (Gitea’s git user) is host UID 100000 + 999 = 100999. Files that Gitea creates with mode 0600 belong to 100999, and you can’t read them from the host. The repository objects were 0644 in 0755 directories, so tar read those, and the archive looked complete.

tar does complain, on stderr, and exits with status 2. In tar c ... | bzip2 > file, though, the pipeline’s exit status is bzip2’s, which is 0. Without set -o pipefail and someone reading the job’s stderr, nothing tells you.

Fix the backup

Run tar inside the user namespace, where you are root over every mapped UID:

set -o pipefail
podman unshare tar c -C ~/gitea/data gitea | bzip2 -z9 > ~/backup/gitea-data-$(date +%y%m%d).tar.bz2

The archive then records the IDs as the container sees them (1000), not the host’s 100999.

To rescue the files without touching the live host, fetch only the missing ones the same way, then merge them into the old archive with bsdtar’s @archive syntax:

ssh vps.example.com 'cd ~/gitea/data && podman unshare tar -c -T -' < missing.txt > missing.tar
bsdtar -czf gitea-complete.tar.gz @gitea-data.tar.bz2 @missing.tar

Fix the restore

GNU tar run as root restores the owners recorded in the archive (--same-owner is its default for root). Inside an unprivileged LXC container, root is itself a mapped user, and the container’s UIDs usually cover only 0 to 65535. UID 100999 doesn’t exist there, so chown fails with EINVAL, which tar reports as Invalid argument.

Don’t restore owners from an archive made somewhere else. Unpack with --no-same-owner and set the owners the new Gitea expects:

tar -C /var/tmp/gitea-restore --no-same-owner -xzf gitea-complete.tar.gz
cp -a /var/tmp/gitea-restore/gitea/. /srv/gitea/data/
chown -R 1000:1000 /srv/gitea/data/git /srv/gitea/data/gitea
chown -R root:root /srv/gitea/data/ssh

This also covers the merged archive, which carries 100999 for some files and 1000 for others.

After the restore, check against the live instance: the repository count, git fsck on every repository, and the SSH host key fingerprint on the Git SSH port, so existing clones still trust the new host. All three matched.

Takeaway

Under rootless Podman, a host-side tar leaves out the files the container keeps private, which are often its secrets, and the pipeline still exits 0. Comparing the archive’s listing with podman unshare find takes a minute and shows the gap.

Run the podman unshare find and comm check above against your own latest backup and see what comes back.

APFS sparse bundle on SMB: rsync "Operation not supported (45)" and F_FULLFSYNC

Tue, 29 Sep 2026 12:55:00 +0200

A backup job that rsyncs into encrypted disk images on a NAS started printing this for every file (paths elided):

rsync: [generator] failed to set times on …
rsync: [receiver] mkstemp …
rsync: [generator] delete_file: unlink … failed: Operation not supported (45)

Then hdiutil attach for the next image hung for over ten minutes, and the two images whose rsyncs had finished stayed mounted.

If you keep APFS sparse bundles on an SMB share and see error 45 inside them, the files aren’t the problem. The share can’t do F_FULLFSYNC, and APFS can’t commit a single transaction without it.

The setup

macOS 27.0.1 dropped AFP, so an old NAS that speaks only SMB 2.1 got mounted over SMB instead. Each backup source has its own AES-256 sparse bundle on the share, created like this:

hdiutil create -encryption AES-256 -type SPARSEBUNDLE -size 50g \
 -fs APFS -volname app -stdinpass /Volumes/backup/staging/app.sparsebundle

The job attaches a bundle, rsyncs a server’s files into it, and detaches it.

The kernel log

rsync names the files, so the obvious suspects are permissions or the files themselves. The kernel log points at the image instead (timestamps shortened, process column removed):

/usr/bin/log show --last 90m --style compact \
 --predicate 'process == "kernel" AND eventMessage CONTAINS "apfs"'

12:43:53.531 disk7s1 mount-complete volume app, requested by: mount_apfs (pid 82535); parent: mount (pid 82534)
12:43:53.532 disk7s1 Host is remote
...
12:47:45.393 (apfs) tx_flush_thread:1678: disk7 tx_flush(8311) failed, 45, # 297
12:47:45.931 (apfs) tx_flush_thread:1678: disk7 tx_flush(8311) failed, 45, # 298

APFS noticed the image lives on a remote host. From 24 seconds after mounting, it failed to flush a transaction about twice a second, with error 45 (ENOTSUP). The second mounted image did the same. Nothing written inside them was being committed.

The probe

Error 45 from a flush suggested the sync call, not the write. This script tries plain fsync and the two stronger syncs macOS offers. Run it from a directory on the share:

import fcntl, os
p = "_synctest"
fd = os.open(p, os.O_RDWR | os.O_CREAT, 0o600); os.write(fd, b"x" * 4096)
for name, op in (("fsync", None), ("F_FULLFSYNC", 51), ("F_BARRIERFSYNC", 85)):
 try:
 os.fsync(fd) if op is None else fcntl.fcntl(fd, op)
 print(name, "OK")
 except OSError as e:
 print(name, "->", e)
os.close(fd); os.unlink(p)

fsync OK
F_FULLFSYNC -> [Errno 45] Operation not supported
F_BARRIERFSYNC -> [Errno 45] Operation not supported

APFS asks the disk image to flush; the disk image passes that on as F_FULLFSYNC on its band files on the share, and the SMB client says no.

The NAS also had a share called TimeMachineBackup, and Time Machine over SMB needs full sync, so it seemed worth a try. Same result. Its Time Machine backups dated from the AFP days.

What works

Keep the image off the share. The bundles moved to a USB drive, and every healthy one attaches, writes, deletes, and detaches fine there. That’s where the job runs now.

If the image has to stay on the share, use HFS+ inside it. A test bundle on the same share, created with -fs HFS+J instead of -fs APFS, passed everything the job does: rsync with --delete-during, rename, setting times, deletes, detach and reattach.

If the server runs Samba and you control it, fruit:time machine = yes on the share makes vfs_fruit advertise the FULLSYNC volume capability to macOS clients. That should let APFS images commit, but it wasn’t tested here.

Check the images you already have

The failed commits also left damage. When the bundles were copied to the USB drive, one of them wouldn’t mount:

hdiutil: attach failed - no mountable file systems

A read-only check of its volume (fsck_apfs -n) said why:

warning: (oid 0x74e6) om: btn: invalid o_cksum (0xdfbd1ccee26c9006)
** The volume /dev/rdisk8s1 with UUID … was found to be corrupt and cannot be repaired.

Its band files had last been modified during the failed SMB run, and the original on the NAS was identical, so the copy wasn’t to blame. Since it was only a staging mirror, it got recreated empty, and the next run filled it again. After any such episode, attach each image and run diskutil verifyVolume on it.

Why restic didn’t mind

Restic repositories on the same share were unaffected. Restic is written in Go, and Go’s Fsync on macOS tries F_FULLFSYNC and falls back to plain fsync on ENOTSUP. The comment in the Go source names this exact case: “There are scenarios such as SMB mounts where fcntl will fail with ENOTSUP.” APFS inside a disk image has no such fallback: when the full flush fails, it stops committing.

Takeaway

An APFS disk image on an SMB share works only if the share supports F_FULLFSYNC. Without it, every write inside the image fails with error 45, and the failed commits can corrupt the image.

If you’re moving sparse bundles from AFP to SMB, run the probe above on the new share before you mount anything on it.

macOS SMB: OSError: [Errno 9] Bad file descriptor after a silent reconnect

Tue, 29 Sep 2026 12:15:00 +0200

A Python script that had encrypted backup archives on a NAS for months started failing on every run:

Traceback (most recent call last):
 File "/Volumes/backup/./encrypt-one.py", line 74, in <module>
 main()
 File "/Volumes/backup/./encrypt-one.py", line 38, in main
 with open(f, "rb") as src:
OSError: [Errno 9] Bad file descriptor

Then the bash script that called it stopped too. Not intermittently: start the job and something fails sooner or later.

If you run long jobs from an SMB share on macOS and get EBADF on files that are plainly there, the cause is probably a session reconnect you never saw, and the kernel log is the only place that records it.

The setup

macOS 27 dropped AFP, so an old NAS that speaks only SMB 2.1 got mounted over SMB instead. A bash script on the share runs encrypt-one.py on a few archives in parallel with xargs -P. Each run streams a 600 MB archive from the share through openssl enc and writes the result back to the same share.

The dead end

The traceback points at open(), so the first move was to open and read that archive by hand. It worked, and so did a read under xargs -P 3. A file that opens fine and a job that fails anyway tells you the file isn’t the problem. Something happens to the handle while it’s open.

The kernel log

smbutil gave the first hint:

$ smbutil statshares -m /Volumes/backup
...
SMB_VERSION SMB_2.1
SESSION_RECONNECT_TIME 2026-09-29 12:01:17
SESSION_RECONNECT_COUNT 4

Four reconnects; the last one was inside the failed run. The kernel log explains what each one does (timestamps shortened, process column removed):

/usr/bin/log show --last 1h --style compact \
 --predicate 'process == "kernel" AND eventMessage CONTAINS[c] "smb"'

11:58:15.502 (smbfs) smb_iod_sendall: id 0 ts > iod_lastrecv && ts > sr_timesent.
11:58:15.502 (smbfs) smb_iod_reconnect: id 0 Starting reconnect with nas.local
11:58:15.502 (smbfs) smb2_smb_parse_change_notify: smb_rq_reply failed 60
11:58:16.523 (smbfs) smb_iod_reconnect: id 0 The negotiate succeeded to nas.local
11:58:17.065 (smbfs) smb2fs_reconnect_dur_handle: Missing durable handle on <archive.tar.bz2.enc.tmp>
11:58:17.173 (smbfs) smb2fs_reconnect_dur_handle: Missing durable handle on <backup.sh>
11:58:17.186 (smbfs) smb2fs_reconnect_dur_handle: Missing durable handle on <archive.tar.bz2>
11:58:17.205 (smbfs) smb_iod_reconnect: id 0: Reconnect completed successfully.
11:58:17.212 (smbfs) smb2_smb_read_write_async: smb_rq_reply failed 9
11:58:17.212 (smbfs) smbfs_do_strategy: archive.tar.bz2: READ failed with an error of 9
11:58:17.283 (smbfs) smbfs_do_strategy: archive.tar.bz2.enc.tmp: WRITE failed with an error of 9

The NAS stopped answering under sustained I/O (error 60 is ETIMEDOUT). macOS dropped the session and reconnected, and that part worked. Then it tried to reattach each open file; the server had nothing to reattach them to, and every read and write on those files failed with error 9, EBADF.

Look at the middle line: backup.sh is on the list. Bash reads a script from disk as it runs, so the script file is open the whole time and goes bad with everything else. That’s why the shell stopped as well.

Why

A durable handle is how an SMB 2.x client keeps an open file across a dropped connection: the server holds the open for a while, and the client reclaims it after reconnecting. This server granted none. So “Reconnect completed successfully” is true for the session and useless for every file that was open at the time. Nothing reaches the application except EBADF on the next read or write.

What fixed it

Stop running long I/O jobs from the share. The pipeline moved to a USB drive, and only finished files go to the NAS. That ended the failures.

If you can’t move off the share, two workarounds got the job past the failing step:

Make bash read the whole script before it starts, so it never goes back to the share for the next line:
```
#!/usr/bin/env bash
{
set -euo pipefail
# ... the whole script ...
exit
}
```
Bash parses the entire { } block before running any of it, and the exit stops it from reading past the closing brace.
Make the I/O survive a reconnect: process the file in segments (64 MiB worked), open, write and fsync each segment separately, and on EBADF, EIO or EAGAIN reopen and retry only that segment. With AES-CBC you can chain the segments by using the last ciphertext block as the next IV, and the output is byte-identical to one openssl enc pass. In the test run on the share, no reconnect happened at all, probably because the per-segment fsync slowed the writes enough for the NAS to keep up.

If the server is a Samba box you control, check whether it grants durable handles: the durable handles option only takes effect with kernel oplocks = no, kernel share modes = no and posix locking = no. Turning off SMB signing on the client (signing_required=no in /etc/nsmb.conf) might also take enough load off a weak NAS CPU to prevent the stalls. Neither was tried here.

Takeaway

On macOS, an SMB reconnect to a server without durable handles invalidates every open file on the share, including a running shell script, and the only trace is Missing durable handle in the kernel log.

If you’ve seen Errno 9 on an SMB mount, run smbutil statshares -a and look at SESSION_RECONNECT_COUNT before you debug your code.

Uninstalling one Odoo module can remove its dependents and their data

Sun, 30 Aug 2026 00:00:00 +0000

An Odoo module replacement passed a rehearsal’s record-count and accounting-total checks, yet the uninstall also removed a dependent addon that owned important business data. The application still loaded. The acceptance checks had missed the field that mattered.

Before replacing a module, inspect its reverse dependencies and data ownership. Rehearse the corrected transition on a restored copy, then compare the affected values by record identity before approving the live change.

Uninstall computes a reverse-dependency set

In Odoo 18’s module implementation , downstream_dependencies() recursively finds modules that depend on the selected modules. button_uninstall() marks both the selection and those dependents as to remove.

The same source describes module_uninstall() as removing database structures created by the module, including tables and columns. Actual deletion depends on the affected records and metadata; do not assume every business record disappears, or that surviving rows retain every field.

Generalize the replacement to a full addon, a smaller replacement, and an extension that depends on the full addon. Installing the smaller addon does not automatically redirect the extension’s dependency. Uninstalling the full addon still includes that extension in the removal set.

The first rehearsal had the wrong acceptance criteria

The historical transition checked surviving records, aggregate totals, and registry health. Those checks passed while the dependent addon was also uninstalled. The user caught the missing preservation requirement and required a restore.

The subsequent investigation found a second problem: changing the extension’s manifest alone would be insufficient. The smaller replacement did not yet implement a field the extension required. That field’s behavior needed to be ported before changing the dependency.

The retained record includes the corrective restore and a later clone’s uninstall/registry-reload output. It ends with the corrected rehearsal and final verification still open. It does not prove a successful final transition or a completed before/after digest comparison.

Rehearse the field handoff explicitly

A safer transition procedure is:

Quiesce writes and capture a consistent database and filestore backup. Verify checksums and prove that the pair restores.
Record installed module states, reverse dependencies, and the fields and records that must survive. Keep the addon source revisions with the backup.
Implement the required field behavior in the replacement, including compute and reversal behavior where applicable. Version-control the dependent addon too.
On an isolated restore, install the replacement and upgrade the dependent addon so the database’s module metadata reflects the new dependency. Inspect the removal set again before uninstalling the old addon.
Complete the uninstall, reload the registry, and compare the required values and behavior. Investigate field metadata and ownership during the handoff; identical field names alone do not establish safe transfer.

Disable scheduled jobs and outbound integrations on the clone. A rehearsal should not send mail, contact payment services, or write to production storage.

Compare identity and value, not only counts

For a small affected dataset, compare canonical exports directly. For larger exports, a digest is convenient if the query scope, ordering, and serialization remain identical.

This synthetic Python check demonstrates why counts and non-null counts are insufficient. It models two records whose field values were exchanged; it is not an Odoo migration test:

import hashlib
import json


def digest(rows):
 payload = json.dumps(sorted(rows), separators=(",", ":"), ensure_ascii=True)
 return hashlib.sha256(payload.encode("utf-8")).hexdigest()


before = [(1, "2026-01-10"), (2, None), (3, "2026-01-20")]
after = [(1, "2026-01-20"), (2, None), (3, "2026-01-10")]
assert len(before) == len(after)
assert sum(value is not None for _, value in before) == 2
assert sum(value is not None for _, value in after) == 2
assert digest(before) == digest(list(reversed(before)))
assert digest(before) != digest(after)
print("counts match; identity/value digest detects the change")

For a real comparison, export the stable record ID alongside each affected field, preserve nulls, and normalize dates and other types explicitly. A missing column must fail the check. Also test compute behavior and important workflows: a value digest cannot prove those work.

Before your next uninstall, list which dependent addons and field values must remain, and make their survival a rehearsal acceptance criterion.