Two Days of Debugging: A One-Character Story

Or: How I Learned to Read the F***ing Manual (An Arch Linux Horror Story)

You know that feeling when you're absolutely certain something is broken? Like, deep-in-your-bones certain that the tools are lying to you, the documentation is wrong, the kernel is bugged, and reality itself is conspiring against your rice setup?

Yeah. I just spent two days in that hell. On Arch Linux. Where I'm supposed to know better.

(Narrator: He did not, in fact, know better. He knew nothing. He was Jon Snow with a mechanical keyboard.)

It Started So Innocently

I wanted a wallpaper changer. Simple, right? JUST A WALLPAPER CHANGER. I wasn't asking for a cure for cancer or a girlfriend. Just something clean with a nice menu using wofi.

I found swww - looked cool, worked great for Wayland. Then I thought, "Hey, you know what would be even cooler? If my ENTIRE DESKTOP automatically re-themed itself based on the dominant colors of the wallpaper I just picked."

Classic Arch user mindset: "It works? That's boring. Let's make it complex."

(Spoiler: I didn't make it better. I made a digital war zone.)

The Setup (Recipe for Disaster)

Here's my "perfect" stack:

• Arch Linux (btw) - because I apparently enjoy suffering
• Wayland (Hyprland) - because Xorg is for boomers
• swww - for those buttery smooth transitions that justify my $2000 GPU
• wofi - because I need my menu to look aesthetic while I launch htop to see why my ram is gone
• PyWal - the GOAT of color generation
• Me - A developer with 0 brain cells and infinite confidence

The script was beautiful. wofi pops up. I pick "Cyberpunk City". swww transitions. PyWal extracts the neon blues and pinks. My terminal, my bar, my soul—everything becomes aesthetic.

It. Was. Perfect.

For about 5 minutes.

Then I opened a file manager.

The Horror Reveals Itself

I opened Nautilus (GTK file manager).

The colors were... wrong.

Not "slightly off" wrong. Not "needs tweaking" wrong. We are talking radioactive vomit wrong.

The background was this sickly brownish-grey. The text was unreadable neon green. The borders were... purple? It looked like someone fed a color wheel through a blender set to "Help Me" and threw the results at my monitor.

"Must be PyWal," I thought. "I'm an engineer. I solve problems."

I cracked my knuckles. I put on my hacking playlist (Lofi Beats to Debug/Cry To). I was ready.

(Narrator: He was not ready.)

I dove into configs. I tweaked templates. I regenerated tables. I restarted Hyprland. I rebooted (the shame!).

Nothing worked. My GTK apps looked like they were designed by a colorblind AI trained exclusively on MySpace profiles from 2004.

Then I found wpgtk on Reddit. "It integrates PyWal with GTK themes! It's the missing link!"

"Aha!" I shouted at my empty room. "The solution!"

yay -S wpgtk-git

I added it to my script. I ran it. I waited for salvation.

It got worse.

Now the colors weren't just ugly—they were changing RANDOMLY every time I re-applied them. One second it's brown, the next it's puke green.

Two Days of Descent into Madness

For 48 hours, I ceased to be a human being. I became a machine that turns coffee into frustration.

I was convinced the universe was broken.

"Is it Wayland?" I screamed. "Is it Hyprland? Is it the NVIDIA DRIVERS??" (It's always the Nvidia drivers, except when it isn't).

I checked:

• PyWal configs (Perfect)
• wpgtk settings (Flawless)
• Env vars ( Pristine)
• My sanity (404: Not Found)

I was reading forum posts from 2017. "User 'xX_Linuxgod_Xx' had this issue. He fixed it by reinstalling Arch."

Don't tempt me, Satan.

I reached that special stage of debugging where you start inventing conspiracies. Maybe the maintainer of wpgtk hates me specifically. Maybe he pushed a commit just to ruin my Tuesday.

"I could write my own color scheme generator in Rust!" I declared at 3 AM.

I was dead serious. I was mentally architecting wal-rs.

• "It'll use SIMD for color extraction!"
• "It'll be memory safe!"
• "It'll be blazingly fast!"
• "It won't SUCK like this python garbage!"

The hubris. The absolute unmitigated arrogance. I was one failed command away from rewriting the entire Linux desktop ecosystem because I couldn't get my folder icons to be the right shade of blue.

The README Strikes Back

Finally, defeated, broken, and running on 3 hours of sleep, I did the unthinkable. The act of last resort. The thing we only do when all hope is lost.

I read the documentation.

Not skimmed. Read.

Buried in the wpgtk wiki, I found this sentence:

"wpgtk runs PyWal internally to generate color schemes from the wallpaper."

My heart stopped.

I read it again.

"wpgtk runs PyWal internally..."

My script looked like this:

# STUPID SCRIPT V1
wal -i "$wallpaper"   # Run PyWal to generate colors
wpg -a "$wallpaper"   # Add wallpaper to wpgtk (which ALSO runs PyWal)

I WAS RUNNING IT TWICE.

1. wal -i runs. It picks a palette (PyWal uses k-means, it's slightly random/non-deterministic). It sets the colors.
2. wpg -a runs immediately after. It runs PyWal AGAIN internally. It picks a slightly different palette because math is hard.
3. Both processes fight to the death over who gets to write to ~/.cache/wal/colors.json.
4. My GTK theme gets updated with a corrupted mix of Palette A and Palette B.
5. The result is Aesthetic Chernobyl.

I had created a Race Condition. In a bash script. For my desktop wallpaper.

I wasn't a victim of bad software. I was a victim of my own inability to read one sentence.

The One-Character Fix

The fix wasn't a kernel patch. It wasn't a Rust rewrite. It wasn't a sacrifice to the pagan gods.

It was changing a to r.

# THE FIX
# wpg -a (add/generate) -> wpg -r (reload/apply current)
wpg -r 

wpg -r just tells wpgtk: "Hey, use the colors that are ALREADY THERE. Don't think. Just apply."

One character.

a -> r.

Two days. 48 hours. 12 coffees. A threatened relationship.

And the solution was replacing one letter.

I changed the letter. I ran the script.

Everything worked. Instantly. Perfectly. Beautifully.

I didn't feel joy. I didn't feel relief. I felt a deep, hollowing emptiness. I stared at my perfect desktop, my perfectly matching colors, my beautiful GTK theme... and I wanted to punch my monitor.

The Lesson (That I Will Definitely Forget)

They say "RTFM" (Read The F***ing Manual) is rude.

It's not rude. It's a desperate plea to save you from yourself.

If I had spent 2 minutes reading, I would have saved 2 days of debugging. But no. I'm a "Senior Developer." I don't "read." I "intuit." I "figure things out."

I intuited my way into a mental breakdown.

TL;DR

• Don't run PyWal and wpgtk together. They hate each other.
• wpg -a generates. wpg -r applies. Know the difference.
• Read the docs.
• No, really. READ THEM.
• If you think "I can rewrite this better in Rust," go to sleep. You're drunk on hubris.

Now if you'll excuse me, I'm going to go stare at my wall. It doesn't have a theme. It doesn't have a config file. It's just a wall. And right now, that's the most beautiful thing I've ever seen.

(Written from my customized Arch setup which looks dope af now btw)