Google Ads Header Ready

Claude Code + Immich: Fixing a 5GB Stuck Upload on My Home Server

Claude Code and Immich home server illustration showing a 5GB stuck upload problem, Ubuntu CLI logs, Syncthing, and Pixel photo backup. 

This post is a personal record of how I started using Claude Code CLI as a second pair of eyes for my Immich home server. The setup is not fancy cloud infrastructure. It is an old laptop at home, running Ubuntu CLI only, with Immich, Portainer, Syncthing, and my Pixel 5 photo backup workflow around it.

Short version: Claude Code helped me troubleshoot my Immich home server by reading error logs, checking folders, finding a stuck upload that silently used around 5GB of space, helping with Syncthing paths, and making Immich updates feel less risky.

The most useful part was not that Claude Code “controlled” my server. The useful part was that it helped me understand what was happening before I touched anything dangerous.

Jump to

My Immich Home Server Setup

My Immich server runs on an old laptop in my house. The machine is not a normal desktop environment. It is basically Ubuntu CLI only, so most of the real work happens through terminal commands, logs, Docker containers, and folders.

The main pieces are:

  • Old laptop home server: the machine that runs Immich.
  • Ubuntu CLI: no fancy desktop workflow, mostly terminal.
  • Portainer: what I use to manage containers visually.
  • Immich: the photo and video backup app.
  • Syncthing: part of my file movement and backup flow.
  • Pixel 5: part of my Google Photos backup strategy.

I am not currently running Immich through a public tunnel. My Cloudflare Tunnel setup is more like a frozen/paused version for this part. For this Immich setup, I treat it as a home-server workflow, not something I want to expose casually.

Family phones
  ↓
Immich on old laptop home server
  ↓
Syncthing / backup folders
  ↓
Pixel 5 / Google Photos backup workflow

This connects to my older photo backup notes, especially:

Why I Used Claude Code With Immich

I already wrote about how Claude Code changed my server workflow in From Copy-Pasting YAML to Managing Servers with Claude Code CLI. Immich is one of the best examples of why that matters.

Before this, my normal workflow was:

  1. Something breaks.
  2. I copy an error log.
  3. I paste it into an AI chatbot.
  4. The chatbot guesses based on partial information.
  5. I go back to the server and try to connect the dots myself.

That works sometimes, but it is tiring. With a photo server, it is also risky. Photos and videos are not random test files. If I delete the wrong folder or misunderstand a storage path, I may break something that matters to my family.

Claude Code helped because it could look at the server context more directly. It could help me read logs, understand where files were stored, and think through the risk before making a change.

The 5GB Stuck Upload Problem

The most memorable problem was a failed video upload.

One upload crashed halfway. The video did not finish uploading properly from the phone, but it also did not cleanly disappear. It became stuck in the Immich upload folder, using about 5GB of storage.

The annoying part was that Immich itself seemed to miss it. From my side, I only knew something felt wrong:

  • The phone could not properly retry the upload.
  • The upload did not complete like normal.
  • Storage space was being used, but I did not know why.
  • The stuck video was sitting in the upload folder like a hidden blockage.

This is the kind of problem that scares me more than a normal error message. A visible error is easy to notice. A half-failed upload quietly using space is much easier to miss.

Claude Code helped by checking the error logs and folder structure with me. Instead of randomly deleting things, I could ask questions like:

  • Which folder is the upload folder?
  • Which folder is the source folder?
  • Is this file already imported into Immich?
  • Is this failed upload safe to investigate?
  • Why can the phone not retry the upload?

The important lesson was simple: failed uploads can become hidden storage problems. If you run Immich on a small home server, you should not only check the app UI. You should also understand the storage folders behind it.

Quick Checklist for Immich Stuck Upload Problems

If I see another failed Immich upload, this is the checklist I want to follow before deleting anything:

  • Check the phone first: confirm whether the mobile app can retry the upload or keeps failing.
  • Check Immich logs: look for upload, database, storage, or container errors.
  • Check disk usage: find whether one folder suddenly gained several GB.
  • Check the upload folder: failed temporary files may still be sitting there.
  • Confirm the source folder: do not confuse original files with generated thumbnails or temporary upload files.
  • Verify before cleanup: do not delete photo or video files just because a folder looks too large.

Checking Syncthing and Source Folders

Claude Code also helped me understand my Syncthing and image folder setup better.

At first, I did not fully know which folder was the source folder and which folder was part of the generated or synced flow. That matters because in a photo backup system, not every folder has the same meaning.

Some folders may contain:

  • original uploads,
  • temporary upload files,
  • Immich library files,
  • Syncthing synced files,
  • thumbnail or generated files,
  • files waiting to move to the Pixel 5 flow.

If you do not know which is which, cleanup becomes dangerous.

Wrong way:
"This folder is big, delete it."

Safer way:
"What is this folder used for?
Is it source data, generated data, or failed temporary upload data?
Can I verify it before removing anything?"

This is where Claude Code felt useful. It did not just give a one-line answer. It helped me reason through the folder purpose and connect the logs to the actual files.

Updating Immich More Safely

Another useful task was updating Immich. In my own notes, I referred to the setup as Immich version 3. The exact version number matters less than the lesson: Immich updates are not something I want to do blindly.

Immich is still a fast-moving project. Updates can include changes to the app, database, machine learning container, storage logic, or mobile app compatibility. For a normal test app, I might just update and see what happens. For a photo backup app, I prefer to slow down.

Claude Code helped by making the update process feel more structured:

  • check current containers,
  • read error logs first,
  • understand what might change,
  • avoid deleting folders blindly,
  • check if Immich comes back properly after update,
  • look for obvious errors after restart.

That does not mean AI becomes the backup plan. It means AI helps me avoid making emotional, rushed terminal changes when I am not fully sure what is happening.

What I Do Not Let AI Do Blindly

This part is important. I do not treat Claude Code as magic. I treat it as a careful assistant.

For my Immich server, I do not want AI to blindly:

  • delete photo or video folders,
  • remove volumes without checking,
  • expose Immich publicly through a tunnel,
  • change Docker settings without explanation,
  • assume failed uploads are safe to erase,
  • replace a real backup strategy.

The best use is not “AI, fix my server.” The better use is:

“Help me understand what is happening, what is risky, and what I should verify before touching anything.”

What I Learned

  • Logs matter: Immich errors are easier to understand when someone helps connect them to the folder structure.
  • Failed uploads can hide: a crashed upload can still use real disk space.
  • Know your source folder: not every large folder is safe to clean.
  • Portainer is useful, but not enough: sometimes you still need to understand the server behind the UI.
  • Claude Code is a second pair of eyes: it is useful because it can help inspect and explain, not because it should act blindly.

Frequently Asked Questions

Can Claude Code manage Immich?

Claude Code can help manage an Immich server if it has access to the right server context. In my case, it helped read logs, check folders, understand Syncthing paths, and think through update risks. I still treat final actions carefully.

Is my Immich server exposed through Cloudflare Tunnel?

No, not for this setup right now. My tunnel setup is more like a frozen/paused version. For Immich, I am more careful because it contains personal and family photos.

Can failed Immich uploads use storage?

Yes, based on my experience. A video upload crashed halfway and stayed in the upload folder, using around 5GB of disk space even though the upload did not complete normally.

Why use Portainer and Claude Code together?

Portainer gives me a visual way to manage containers. Claude Code helps me understand logs, folders, and server-side details that are not always obvious from the UI.

Should AI delete Immich files automatically?

No. For a photo server, deletion should be slow and verified. AI can help identify what a folder might be, but I still want checks before removing anything.

Final Note

This is why I like Claude Code for home server work. It does not turn me into a professional sysadmin overnight, and it does not remove the need to learn. But it helps me ask better questions, read scary logs with less panic, and avoid touching folders I do not understand.

For a normal app, that is convenient. For a photo backup system, that extra caution matters.

Tags:
Harvard Chin Yihao

Harvard Chin Yihao

I explore tech, markets, and build in public. Documenting my journey, practical insights, and DIY projects. Join me as I learn and grow. View Linktree

Posted by at
Labels:

Comments

Subscribe to: Post Comments (Atom)