Debugging

You’ve set DATABASE_URL in your .env file. You’ve exported it in your shell. But your application still can’t find it. Sound familiar? Environment variable issues are one of the most common — and frustrating — debugging sessions. Here’s a systematic guide to finding and fixing the problem. The Quick Checklist Before diving deep, check these common culprits: Did you restart your application? Environment variables are read at process start Are you in the right shell session? Variables exported in one terminal don’t exist in another Is your .env file in the right directory? Most libraries look in the current working directory Did you spell it correctly? DATABASE_URL vs DATABSE_URL happens more than you’d think Python: The os.environ Mystery Problem: KeyError When Accessing Variables 1 2 import os database_url = os.environ['DATABASE_URL'] # KeyError! Fix 1: Check if the variable exists first ...

You added a cron job. It should be running. It isn’t. The logs are silent. This is one of the most frustrating debugging experiences in Linux administration because cron fails silently by default. Here’s a systematic checklist to find the problem. 1. Is crond Actually Running? First, verify the cron daemon is running: 1 2 3 4 5 6 7 # systemd systems systemctl status cron # or systemctl status crond # Older init systems service cron status If it’s not running, start it: ...

You’ve deployed your webhook endpoint. The external service says it’s sending requests. But your logs show nothing. Here’s how to systematically debug incoming webhook issues. The Debugging Checklist Before diving deep, run through these quick checks: 1 2 3 4 5 6 7 8 9 10 11 # 1. Is your endpoint actually reachable? curl -X POST https://your-domain.com/webhook \ -H "Content-Type: application/json" \ -d '{"test": true}' \ -w "\nHTTP Status: %{http_code}\n" # 2. Is DNS resolving correctly? dig your-domain.com +short # 3. Is the port open? nc -zv your-domain.com 443 If your own curl request doesn’t reach the endpoint, the problem is infrastructure. If it does but the external service’s requests don’t arrive, the problem is somewhere in between. ...

Your container is restarting. Over and over. docker ps shows it’s been up for 3 seconds, then 5, then 2. You’re stuck in a loop and the logs aren’t helping. Here’s how to debug it systematically. Step 1: Check the Exit Code 1 docker inspect --format='{{.State.ExitCode}}' container_name Common exit codes: 0: Clean exit (container finished its job) 1: Application error (check your code) 137: OOMKilled (out of memory) 139: Segfault 143: SIGTERM (graceful shutdown) If you see 137, your container is being killed for using too much memory. Skip to the OOM section below. ...

You’ve written a script. You test it manually: ./my-script.sh — works perfectly. You add it to cron, wait for the scheduled time… nothing happens. No output, no errors, just silence. This is one of the most frustrating debugging experiences in Linux. Let’s fix it. The Core Problem: Cron Runs in a Different Environment When you run a script manually, you’re running it in your interactive shell with: Your PATH variable (with all your custom directories) Your environment variables (loaded from .bashrc, .profile, etc.) Your current working directory Your user’s full shell configuration Cron runs scripts in a minimal environment with almost none of this. That’s the root cause of nearly every “works manually, fails in cron” issue. ...

Your systemd service is “active (running)” but the application isn’t responding. No errors in systemctl status. The journal shows it started. Everything looks fine. Except it isn’t. This is one of the most frustrating debugging scenarios in Linux administration. Here’s how to actually figure out what’s wrong. The Problem: Green Status, Dead Application 1 2 3 4 5 $ systemctl status myapp ● myapp.service - My Application Loaded: loaded (/etc/systemd/system/myapp.service; enabled) Active: active (running) since Fri 2026-03-20 10:00:00 EDT; 2h ago Main PID: 12345 (myapp) Looks healthy. But curl localhost:8080 times out. What’s happening? ...

You’re using Python’s imaplib to search emails, but mail.search() keeps returning empty results even though you know matching emails exist. Here’s why it happens and how to fix it. The Problem 1 2 3 4 5 6 7 8 9 import imaplib mail = imaplib.IMAP4_SSL('imap.gmail.com') mail.login('user@gmail.com', 'app-password') mail.select('INBOX') # This returns nothing! status, messages = mail.search(None, 'FROM "john@example.com" SUBJECT "invoice"') print(messages) # [b''] You’ve verified the emails exist. You can see them in Gmail. But search() returns an empty byte string. ...

You wrote what looks like perfectly reasonable Python code: 1 2 3 4 5 6 7 8 9 10 11 12 import subprocess proc = subprocess.Popen( ["some-command"], stdout=subprocess.PIPE, stderr=subprocess.PIPE ) # Read the output output = proc.stdout.read() errors = proc.stderr.read() proc.wait() And it hangs. Forever. No error, no timeout, just… nothing. Welcome to the pipe buffer deadlock, one of Python’s most frustrating subprocess gotchas. Why This Happens The problem is OS pipe buffers. When you create a subprocess with stdout=subprocess.PIPE, the OS creates a pipe with a fixed buffer size (typically 64KB on Linux). ...

Your logs are probably useless. Not because you’re not logging, but because you’re logging wrong. Here’s how to make logs that actually help when things break. The Problem with Unstructured Logs [ [ [ 2 2 2 0 0 0 2 2 2 4 4 4 - - - 0 0 0 3 3 3 - - - 1 1 1 2 2 2 1 1 1 0 0 0 : : : 2 2 2 3 3 3 : : : 4 4 4 5 6 7 ] ] ] I E P N R r F R o O O c : R e : s U s s S i e o n r m g e l t o o h r g i d g n e e g r d w f i e o n n r t u w s r e o r n g 1 2 3 4 5 Try answering these questions: ...

Your pod won’t start. The service isn’t routing. Something’s wrong but kubectl isn’t telling you what. Here’s how to actually debug Kubernetes problems. The Debugging Hierarchy Work from the outside in: Cluster level — Is the cluster healthy? Node level — Are nodes ready? Pod level — Is the pod running? Container level — Is the container healthy? Application level — Is the app working? Most problems are at levels 3-5. Start there. ...