DEV Community: SystemCraftDev

'ModuleNotFoundError' Right After pip install — You Installed It for a Different Python

SystemCraftDev — Sun, 11 Oct 2026 02:46:10 +0000

The package is installed and Python says it doesn't exist. Both are true: pip and python can belong to different installations. Here's how to see which one is which and how to make them agree.

Adapted from the Python Essentials Companion Guide.

You need a library, so you install it, and pip reports success:

$ pip install termcolor
Successfully installed termcolor-2.4.0

Then you run your script:

$ python app.py
Traceback (most recent call last):
  File "app.py", line 1, in <module>
    import termcolor
ModuleNotFoundError: No module named 'termcolor'

Both messages are telling the truth, which is exactly why this is so frustrating. pip installed termcolor. Python can't find termcolor. Nothing is broken, and nothing was lost. The package is sitting on your machine, just not where the Python that ran your script is looking.

What's actually happening

Most machines have more than one Python on them: the one your operating system ships with, one you installed yourself, one inside a virtual environment, one bundled with an editor or tool. Each of those has its own separate folder of installed packages, called site-packages. A package installed into one copy is invisible to every other copy.

The pip command and the python command are two separate programs that each get found by searching your PATH. Nothing guarantees they point at the same installation. So pip install termcolor may have put the package into Python A's site-packages, while python app.py started Python B, which has never heard of it. When import termcolor runs, Python B searches only its own folders, comes up empty, and raises ModuleNotFoundError.

That's the whole error: "I searched every place this interpreter looks, and the module isn't in any of them." It says nothing about whether the package exists elsewhere on your computer.

The fix, step by step

1. Find out which Python actually ran your script. Add this to the top of the file, or run it in the same terminal:

python -c "import sys; print(sys.executable)"

The path it prints is the interpreter that failed to find your package, for example C:\Python312\python.exe or /usr/bin/python3.

2. Find out where pip installs things.

pip --version

The output ends with a path and a Python version, something like pip 24.0 from /home/you/.venv/lib/python3.12/site-packages/pip (python 3.12). If that path points to a different Python than the one from step 1, you've found the mismatch.

3. Install through the interpreter itself, so the two can't disagree. Instead of running pip directly, run it as a module of the exact python you use:

python -m pip install termcolor

On Windows, if you run scripts with the launcher, use py -m pip install termcolor. Because python -m pip is pip belonging to that interpreter, the package lands in the same site-packages your script will search. Run your script again and the import works.

4. If you use a virtual environment, activate it before you install or run anything. The activated environment puts its own python and pip at the front of your PATH:

source .venv/bin/activate      # macOS / Linux
.venv\Scripts\activate         # Windows

You can confirm it worked: sys.executable from step 1 should now point inside your .venv folder.

Two mistakes worth knowing about ahead of time

Reinstalling the package over and over. Running pip install again feels like it should help, and it only reports "Requirement already satisfied", because pip is checking the installation it belongs to, which already has the package. The repeated message is a sign the install is fine and the interpreter is the problem.

Using the wrong name for the import. Sometimes the package you install and the module you import have different names, and then you get this same error with a perfectly matching interpreter. pip install python-dotenv gives you import dotenv, not import python_dotenv. Other common pairs are Pillow (import PIL), scikit-learn (import sklearn), and opencv-python (import cv2). If python -m pip show <package> finds it but the import still fails, check the package's documentation for the real import name.

Editors add one more layer to this. If the script runs fine in your terminal but your editor shows the same error, the editor is using a different interpreter than your terminal. That case has its own explanation in VS Code Is Running the Wrong Python.*).

A habit that prevents the confusion entirely

Get in the habit of typing python -m pip install ... instead of bare pip install ..., every time. It costs a few extra keystrokes and removes the entire class of problem, because the pip you run is by construction the one that belongs to the Python you named. Pair it with one virtual environment per project, activated before you start working, and "it's installed but Python can't see it" becomes something you can diagnose in under a minute: sys.executable tells you who ran, pip --version tells you who installed, and the two paths either match or they don't.

If you'd like more posts like this sent straight to your inbox, subscribe to the newsletter.

Prefer to dig in yourself? The Python Essentials repo on GitHub has more free examples and exercises.

'Bad Interpreter: No Such File or Directory' — The Script Exists, the Interpreter Doesn't

SystemCraftDev — Mon, 05 Oct 2026 03:35:43 +0000

The file is right there, so why does the shell say it doesn't exist? The error is about the interpreter named on the first line, and usually a hidden carriage return is the culprit. Here's how to see it and fix it.

Adapted from the Command Line Essentials Companion Guide.

You write a small script, make it executable, and run it:

$ ls -l deploy.sh
-rwxr-xr-x 1 you you 62 Oct  4 09:12 deploy.sh

$ ./deploy.sh
bash: ./deploy.sh: /bin/bash^M: bad interpreter: No such file or directory

The file is sitting right there, ls just showed it, and the permissions are fine. Yet the shell insists something doesn't exist. This is one of the more disorienting errors in the shell, because the message sounds like it's about your script and it isn't. It's about a different file entirely: the interpreter named on the script's first line. And if you look closely at the message, there's a clue sitting in the path: /bin/bash^M.

What's actually happening

When you run ./deploy.sh, the shell doesn't execute the text file itself. The operating system looks at the first line, the shebang (#!/bin/bash), takes the path after #! as the program that should run the script, and launches that program with your script as its argument. If that interpreter path doesn't point to a real file, the launch fails with "No such file or directory". The "file" it can't find is the interpreter, not your script.

So why would /bin/bash not exist? Because the path isn't /bin/bash. Look at the ^M at the end. That's how terminals display a carriage return character (\r), the extra invisible character Windows puts before every newline. A file saved with Windows-style (CRLF) line endings has its first line stored as #!/bin/bash\r\n. Linux and macOS treat only \n as the line break, so the \r stays attached to the end of the path. The system goes looking for a program literally named bash followed by a carriage return, finds nothing, and reports the mismatch.

Nothing is wrong with your commands. The file just arrived with the wrong kind of line endings, usually because it was written in a Windows editor, copied from a Windows machine, or checked out of Git on Windows with automatic line-ending conversion turned on.

The fix, step by step

1. Confirm it's line endings. The file command reports them directly:

$ file deploy.sh
deploy.sh: Bourne-Again shell script, ASCII text executable, with CRLF line terminators

"With CRLF line terminators" is the diagnosis. If you want to see the characters themselves, cat -A deploy.sh shows each carriage return as ^M and each line end as $.

2. Strip the carriage returns. Any of these works:

dos2unix deploy.sh

sed -i 's/\r$//' deploy.sh

dos2unix is the cleanest if it's installed (sudo apt install dos2unix on Debian and Ubuntu). The sed command needs nothing extra: it deletes a trailing \r from every line, in place.

3. Run it again. Nothing else about the script needs to change, and the executable bit survives the edit:

$ ./deploy.sh

4. Stop it from coming back. Fixing the file once doesn't help if your editor or Git reintroduces the problem next time. In VS Code, click CRLF in the bottom-right status bar and switch it to LF for shell scripts. If the file lives in a Git repository, a .gitattributes line makes the setting stick for everyone who clones it:

*.sh text eol=lf

Two mistakes worth knowing about ahead of time

Retyping the shebang line and hoping for the best. Deleting and retyping #!/bin/bash in the same editor will often produce the same CRLF ending again, because the editor is what's adding it. Fix the setting, not just the line.

Assuming ^M errors only affect the first line. Every line in the file has the carriage return, which is why scripts without a shebang fail in a different, stranger way: running them with bash deploy.sh can produce errors like $'\r': command not found partway through, because each line's trailing \r is treated as part of the command. Different message, same root cause. If you see \r or ^M anywhere in shell error output, check line endings first.

The same error message also appears when the interpreter path is genuinely wrong, for example #!/usr/bin/python on a system that only has python3. If file reports no CRLF terminators, check that the path on the first line points at something that exists (ls /usr/bin/python), or use #!/usr/bin/env python3 so the system finds it for you.

A habit that prevents the confusion entirely

When "No such file or directory" appears for a file you can plainly see, ask which file the error is actually about. If you're running a script, the answer might be the interpreter on the first line rather than the script itself. Run file on the script and read the first line with head -1 deploy.sh | cat -A. Two quick commands will tell you whether you have a wrong path or an invisible character, and either way the error stops being mysterious.

If you'd like more posts like this sent straight to your inbox, subscribe to the newsletter.

Prefer to dig in yourself? The Command Line Essentials repo on GitHub has more free examples and exercises.

Why VS Code's Debugger Skips Your Breakpoint — It's Not Broken, It's Not Watching That Line

SystemCraftDev — Wed, 30 Sep 2026 03:23:23 +0000

A hollow breakpoint dot isn't VS Code ignoring you — it's telling you the debugger couldn't connect that line to any code it's actually running. Here's what that means and how to fix it.

Adapted from the VS Code Essentials Companion Guide.

You set a breakpoint, click the line, and the usual solid red dot shows up. You start debugging, and the moment execution should hit that line, nothing happens — the code just keeps running past it. Looking back at the gutter, the dot has changed: it's now hollow, a grey circle with a hole in the middle instead of a solid one. Nothing crashed, no error appeared, the debugger just quietly decided not to stop there.

That hollow dot is the whole story, and it's more specific than it looks. VS Code calls this an "unverified" breakpoint, and the name is accurate: it isn't marking the line as wrong, or your code as broken. It's telling you that the debugger could not connect this exact line in your editor to any line in the code it's actually executing right now. A verified breakpoint (solid red) means the debug adapter found a matching, runnable line and is watching it. An unverified one means it looked and found nothing to bind to — so there's nothing for it to pause on, no matter how many times you run past it.

What's actually happening

When you start a debug session, VS Code doesn't debug the file you're looking at directly — it hands a running process to a debug adapter (one per language/runtime), and that adapter reports back which lines in which files actually correspond to real, loaded, executable code. Your breakpoint only turns solid once the adapter confirms that mapping exists. Until then, or if it never can, the dot stays hollow.

The most common reason that mapping fails is a mismatch between the file you're editing and the file that's actually running. For compiled or transpiled languages — TypeScript compiling to JavaScript, or any bundler-based JS project — the runtime executes generated output, not your source file. A source map is what lets the debugger translate "line 42 of your .ts file" into "line 187 of the bundled .js file the browser or Node process is actually running." If that source map is missing, stale, or points at the wrong output location, the debugger has no way to make that translation — so a breakpoint on your source line has nothing on the runtime side to bind to, and it stays unverified.

The second common cause is simpler: you're debugging a different copy of the code than the one you're editing. A dist/ or build/ folder holding yesterday's compiled output, a Docker container running a stale image, or a launch.json outFiles setting pointing somewhere that no longer matches your source layout — all of these mean the process VS Code attached to isn't running the code in front of you, even though the file names might look identical.

The fix, step by step

1. Confirm it's actually unverified, not just unhit. Hover over the hollow dot — VS Code shows a tooltip explaining why, and for source-map issues it's usually explicit about not being able to find the generated code. That tooltip is worth reading before changing anything; it tells you which of the causes below you're actually dealing with.

2. For compiled/transpiled code, check that source maps are being generated and referenced correctly. Confirm your build config actually emits .map files ("sourceMap": true in tsconfig.json, or your bundler's equivalent flag), and that your launch.json has an outFiles entry pointing at where the compiled output actually lands — a mismatch here is the single most common cause of this exact symptom.

3. Confirm you're running the code you think you're running. Stop the debug session, delete or rebuild your dist/build output, and restart. If the breakpoint verifies immediately after a clean rebuild, the previous run was executing stale compiled output, not your current source.

4. If you're attaching to an already-running process (a container, a remote server, a long-running dev server you didn't start from VS Code), double-check that the path mapping between your local source and the remote source matches exactly — a sourceFileMap or remoteRoot/localRoot setting that's slightly off will produce exactly this symptom, because the debugger genuinely can't find your file on the other end.

Two mistakes worth knowing about ahead of time

Assuming a hollow breakpoint means the line is unreachable in your program's logic. It doesn't say anything about your control flow — it says the debugger can't map the line to running code at all. A perfectly reachable, frequently executed line can show as unverified for purely mechanical reasons (a stale build), while a genuinely dead line would show as verified and just never get hit — a different, quieter problem with a different fix.

Restarting the debug session repeatedly without changing anything. If the mapping is broken, restarting the exact same broken setup produces the exact same hollow dot every time. The fix is almost always in the build output or the launch.json configuration, not in the act of starting a new session — check those before assuming it's a fluke.

A habit that prevents the confusion entirely

Any time you're debugging code that goes through a build step — TypeScript, a bundler, a transpiler of any kind — treat source maps as part of your build's correctness, not an afterthought. Confirm they're being generated on every build, not just the first one, and that your launch.json points at the right output directory before you start hunting for why a breakpoint won't stop. A hollow dot isn't VS Code failing to notice your breakpoint — it's VS Code being honest that, as far as the running process is concerned, that line doesn't currently exist.

If you'd like more posts like this sent straight to your inbox, subscribe to the newsletter.

Prefer to dig in yourself? The VS Code Essentials repo on GitHub has more free examples and exercises.

Why Your JOIN Doubled Your Totals — There's No Error, Just the Wrong Number

SystemCraftDev — Sat, 26 Sep 2026 03:27:04 +0000

SQL doesn't warn you when a JOIN multiplies your rows — it just quietly hands back more of them than you expected, and every SUM() and COUNT() downstream inherits the mistake. Here's the exact mechanism, and how to catch it before it ships.

Adapted from the SQL Essentials Companion Guide.

You write a query to total up each customer's orders, and it runs fine — no error, no red text, just a result set:

SELECT customers.name, SUM(orders.amount) AS total_spent
FROM customers
JOIN orders ON orders.customer_id = customers.id
GROUP BY customers.name;

The totals come back too high. Not obviously broken — just off, in a way that's easy to miss until someone downstream notices the numbers don't match the invoice system. There's no error here to read, which is exactly what makes this one harder than a syntax mistake: the query is completely valid SQL, and it's doing precisely what you told it to. It's just not doing what you meant.

What's actually happening

A JOIN doesn't attach related rows to each other one-to-one — it produces every combination of rows that satisfies the join condition. If a customer has three orders, that customer's row from customers gets matched against all three rows from orders, and the join produces three separate rows in the result — one per order, each with the same customer name and id copied across all of them.

That's correct and often exactly what you want. The trouble starts when there's another join, or another table, contributing rows on top of that. Say each order also has multiple line items, and the query joins in a line_items table to look up something about the order:

SELECT customers.name, SUM(orders.amount) AS total_spent
FROM customers
JOIN orders ON orders.customer_id = customers.id
JOIN line_items ON line_items.order_id = orders.id
GROUP BY customers.name;

Now every order row gets duplicated once for each line item on that order — an order with four line items appears four times in the joined result, each copy carrying the same orders.amount. SUM(orders.amount) then adds that same amount in four times over, once per duplicate. Nothing in the query is malformed; the join is doing exactly what a join does. The aggregate is just summing over a result set that's bigger than the one you were picturing — this is usually called a "fan-out," and it's the most common way a JOIN silently corrupts a total.

The fix, step by step

1. Confirm the row count, not just the total. Before trusting any SUM() or COUNT() after a join, run the join alone without the aggregate and check how many rows come back for a customer or order you can verify by hand. If a customer with 3 orders and no line-item join returns 3 rows, but adding the line_items join bumps that to 11, you've found your fan-out.

2. Identify which joined table is one-to-many relative to what you're aggregating. In this example, orders is one-to-many with line_items — the join is multiplying orders, not customers. The fix has to happen at that join, not by changing the SUM() itself.

3. Aggregate the one-to-many side separately, before joining it up, so the multiplication never reaches your main total:

SELECT customers.name, SUM(order_totals.amount) AS total_spent
FROM customers
JOIN (
  SELECT customer_id, amount
  FROM orders
) AS order_totals ON order_totals.customer_id = customers.id
GROUP BY customers.name;

If you genuinely need data from line_items elsewhere in the query, aggregate it in its own subquery (one row per order) before joining that summary in — never join the raw, un-aggregated many-side table into a query that's also summing a different column.

4. When you can't restructure the joins, use DISTINCT or a pre-aggregated CTE as a stopgap — but treat it as a stopgap. SUM(DISTINCT orders.amount) will silently drop legitimate duplicate amounts (two different orders that happen to both be $50), so it trades one silent bug for another. The subquery approach in step 3 is the actual fix; DISTINCT is what you reach for only when you're debugging in a hurry and plan to come back.

Two mistakes worth knowing about ahead of time

Trusting a query because it ran without an error. Fan-out joins are syntactically perfect SQL — there's nothing for the database to reject. The only way to catch this class of bug is checking row counts and spot-verifying a total by hand against a case you already know the right answer for, not waiting for the database to complain.

Adding more joins to a query that already has an aggregate, without re-checking the totals. Every additional JOIN is a potential new fan-out, even if the query worked correctly before you added it. A query that correctly summed order totals yesterday can start silently inflating them today, the moment someone adds one more join to pull in an unrelated column — the aggregate function didn't change, but the row set underneath it did.

A habit that prevents the confusion entirely

Any time a query joins more than two tables and also aggregates with SUM(), COUNT(), or AVG(), ask which table is on the "many" side of each join relative to what you're totaling — and aggregate that side down to one row per key before it reaches the rest of the query, not after. Joins and aggregates are both doing exactly what they're defined to do; the bug is always in which rows exist by the time the aggregate function runs over them, not in the aggregate function itself.

If you'd like more posts like this sent straight to your inbox, subscribe to the newsletter.

Prefer to dig in yourself? The SQL Essentials repo on GitHub has more free examples and exercises.

How to Fix 'Updates Were Rejected' (Without Force-Pushing and Losing Someone's Work)

SystemCraftDev — Wed, 23 Sep 2026 02:18:29 +0000

This message isn't Git blocking you arbitrarily — it's telling you the remote has commits your local branch doesn't have yet. Here's what to actually do instead of reaching for --force.

Adapted from the Git & GitHub Companion Guide.

You finish up some work, run git push, and instead of the usual quiet success, you get this:

$ git push
To github.com:you/project.git
 ! [rejected]        main -> main (fetch first)
error: failed to push some refs to 'github.com:you/project.git'
hint: Updates were rejected because the tip of your current branch is behind
hint: its remote counterpart. Integrate the remote changes (e.g.
hint: 'git pull ...') before pushing again.

Nothing about your code changed, nothing looks broken locally, and the message reads like Git is just refusing to cooperate. It isn't. Git is telling you something specific and true: the remote branch has commits your local branch doesn't have — probably a teammate pushed since you last pulled, or you pushed from another machine — and it won't let your push proceed until you deal with that.

What's actually happening

A normal git push is only allowed to move a branch forward — Git calls this a fast-forward. Your local branch has to already contain every commit that's currently on the remote branch, plus whatever new commits you're adding on top. That's the whole rule.

The rejection means that condition isn't met: origin/main has at least one commit your local main has never seen. If Git let the push through anyway, the only way to make the remote branch match what you're sending is to replace its history — which would silently throw away whatever commit the remote has that you don't. Git isn't being cautious for no reason here. This exact check is what stops you from erasing a commit you didn't even know existed, just because you happened to push first.

The fix, step by step

1. Confirm what you're actually missing. Fetch first, without touching your working files, then look at what's there:

git fetch
git log HEAD..origin/main --oneline

That second command lists commits that exist on the remote but not in your local branch — exactly what the rejection is protecting.

2. Integrate those commits into your branch. Two ways to do this, and the difference matters:

git pull

Fetches and merges the remote changes into your branch, creating a merge commit if both sides have new work. Your local commits stay exactly as they were, just combined with the remote ones.

git pull --rebase

Fetches, then replays your local commits on top of the remote ones instead of merging. History stays linear — no merge commit — but your commits get new hashes, since they're technically new commits built on a different base.

Either is fine for most day-to-day work; which one your team prefers is a style choice, not a correctness one.

3. Resolve any conflicts that come up. If you and the remote both touched the same lines, Git will stop and ask you to resolve them, the same as any merge — this is a separate, normal step, not a sign that something's gone wrong with the push itself.

4. Push again. Your branch now contains every commit the remote has, plus yours — a clean fast-forward, and the push goes through without needing anything special.

Two mistakes worth knowing about ahead of time

Reaching for git push --force to make the rejection go away. Force-pushing tells Git "don't check any of that, just make the remote match my local branch exactly" — which means whatever commit the remote had that you didn't have is now gone from the branch, not merged in, not preserved anywhere obvious. On a shared branch, that's someone else's work disappearing without warning. There are legitimate reasons to force-push — cleaning up your own commits on a branch nobody else has pulled yet, for instance — but "the normal push got rejected" isn't one of them. If you ever do need to force-push deliberately, use git push --force-with-lease instead of plain --force: it still refuses if the remote has commits you haven't fetched, so you can't blow away work you haven't even looked at by accident.

Assuming the hint's "fetch first" means fetching alone fixes it. git fetch only updates your local copy of the remote branch (origin/main) — it doesn't touch your actual working branch or merge anything in. Run just git fetch and then git push again, and you'll get the exact same rejection, because your branch still hasn't changed. You need the integration step — git pull, or git merge origin/main / git rebase origin/main after fetching — not just the fetch.

A habit that prevents the confusion entirely

On any branch other people are also pushing to, pull before you push, not just after you're rejected — especially if it's been more than a few minutes since you last synced. Treat "it's been a while" as the signal to check, the same way you'd check for new messages before replying to a thread. The rejection itself is never the actual problem; it's Git catching you a step behind where the branch actually is. Pulling first just means you find that out before you've already written your push command, instead of after.

If you'd like more posts like this sent straight to your inbox, subscribe to the newsletter.

Prefer to dig in yourself? The Git & GitHub repo on GitHub has more free examples and exercises.

Why console.log Shows 'Promise {}' Instead of Your Actual Value

SystemCraftDev — Sat, 19 Sep 2026 02:26:42 +0000

That's not a broken await — it's JavaScript reporting exactly what the promise's state was the instant you logged it. Here's why the value isn't there yet, and how to actually wait for it.

Adapted from the JavaScript Essentials Companion Guide.

You write a function to fetch a user, call it, and log the result to check it worked:

async function getUser(id) {
  return fetch(`/api/users/${id}`).then(r => r.json());
}

const user = getUser(42);
console.log(user);

Promise { <pending> }

No error, no crash — just that. It looks like the function silently failed, or that console.log is somehow broken. Neither is true. JavaScript is telling you, accurately, exactly what user was at the precise moment you logged it: not a user object, but a promise that hadn't settled yet. That's not a placeholder for a bug — it's a snapshot of real, correct state.

What's actually happening

An async function always returns a promise. Always — even if every line inside it looks like it's returning a plain value. Write return someValue inside an async function, and the caller still gets back a promise that will eventually resolve to someValue, not someValue itself. That's not a special case you opt into; it's what the async keyword does to the function's return type, unconditionally.

Here's the part that actually causes the confusion: getUser(42) starts running immediately, synchronously, right up until it hits something it has to wait on — here, the fetch call. At that point it hands control back to whatever called it and steps aside, to be resumed later once the network response actually arrives. Your console.log(user) on the next line doesn't wait around for that — it runs immediately, the same tick, before the fetch has had any chance to complete. So user genuinely is a pending promise at that instant. console.log isn't lying to you or failing to unwrap something; it's printing the actual, current value of the variable, and that value just happens to be "a promise that hasn't resolved yet."

The fix, step by step

1. Confirm this is the pattern. If logging something that came from an async function (or anything documented as returning a promise, like fetch) prints Promise {<pending>} — or sometimes Promise {<fulfilled>: ...} if it resolved fast enough — you're reading the promise wrapper itself, not the value inside it.

2. Decide where you actually need the resolved value, then await it there, inside another async function:

async function loadProfile() {
  const user = await getUser(42);
  console.log(user); // the actual object, not a wrapper
}

await pauses execution of loadProfile at that line — and only that line, not the whole program — until the promise settles, then hands you the resolved value directly.

3. If you're not inside an async function (top-level script code in some environments, a plain callback, an older codebase), use .then() instead — same waiting, different syntax:

getUser(42).then(user => {
  console.log(user);
});

Anything that needs the resolved value has to live inside that callback, or inside a function you call from it — code after .then(...) in the outer scope still runs before the promise resolves, same as the original bug.

Two mistakes worth knowing about ahead of time

Putting await inside .forEach() and assuming it pauses the outer function. This one catches people who've otherwise fully internalized await:

async function processAll(ids) {
  ids.forEach(async (id) => {
    const user = await getUser(id);
    console.log(user);
  });
  console.log("done");
}

"done" logs first, before any user prints. forEach doesn't know or care that its callback is async — it fires off each callback and moves on immediately, never looking at (or waiting for) whatever promise that callback returns. The await inside is real, but it only pauses that one callback invocation, not processAll itself. A plain for...of loop with await inside it does pause the outer function on each iteration; forEach, map, and friends never will, regardless of what's inside the callback.

Assuming async on a function means callers automatically get the resolved value. async changes what happens inside the function and what it returns — it doesn't change how someone calling it behaves. The function itself has no way to force a caller to await it; forgetting to is a silent, no-error mistake, which is exactly why it's easy to ship.

A habit that prevents the confusion entirely

Any time you call something you know returns a promise — your own async function, fetch, a library method documented as async — and the very next line uses the result, ask whether that line actually waited for it. If there's no await and no .then() wrapping it, it didn't, no matter how the code reads. console.log printing Promise {<pending>} isn't a separate bug to debug — it's the same missing-await mistake, just surfaced at the one place you happened to look at the value instead of wherever it was actually going to be used.

If you'd like more posts like this sent straight to your inbox, subscribe to the newsletter.

Prefer to dig in yourself? The JavaScript Essentials repo on GitHub has more free examples and exercises.

Python's 'UnboundLocalError' — It's Not a Missing Variable, It's Scope Decided in Advance

SystemCraftDev — Wed, 16 Sep 2026 03:10:44 +0000

The variable has a value elsewhere in your program — just not in the scope Python already decided this line belongs to. Here's how Python actually assigns scope, and why the fix usually isn't global.

As featured in PyCoder's Weekly, Issue #753.

Adapted from the Python Essentials Companion Guide.

You write a small counter function, and it looks completely reasonable:

count = 0

def increment():
    count += 1
    return count

increment()

UnboundLocalError: local variable 'count' referenced before assignment

This one throws people harder than most, because count obviously exists — it's sitting right there on the line above, initialized to 0. The error sounds like Python has lost track of a variable that plainly exists. It hasn't. Python made a decision about this function before it ever ran a single line of it, and that decision, not a missing value, is what's crashing.

What's actually happening

Before a Python function runs, Python scans its entire body — top to bottom, in advance — looking for any name that gets assigned to anywhere inside it. If a name is assigned anywhere in the function, Python marks that name as local to the function, for the entire function body, no matter where the assignment happens to sit or whether it actually runs before other lines that use the name.

count += 1 is shorthand for count = count + 1 — it's an assignment. So Python sees an assignment to count inside increment() and decides, upfront, that count is a local variable of that function. That decision applies to the whole function, including the read on the right-hand side of count + 1, which now happens before Python has assigned anything to that local count. The count = 0 sitting above the function is a completely different variable, at module scope, that the function's local count now shadows — and it doesn't get consulted at all.

That's the whole error, restated precisely: "you're reading a local variable, at a point in the function where it hasn't been given a value yet." It's not that count doesn't exist anywhere — it's that this count, the one this function decided you meant, hasn't been assigned to yet at the line where you're reading it.

The fix, step by step

Confirm you're hitting this pattern: a variable read and assigned in the same function, where the outer/global version was meant to be reused rather than shadowed. If the traceback names a variable you expected to come from outside the function, this is almost always what's happening.
Decide whether the function actually needs to mutate shared state. Usually it doesn't, and that's the better fix:
```
count = 0

def increment(n):
    return n + 1

count = increment(count)
```
Pass the value in, return the new value, and let the caller decide what to do with it. No scope trickery required, and the function is easier to test in isolation.
If the function genuinely needs to rebind a module-level name, tell Python that on purpose with global:
```
count = 0

def increment():
    global count
    count += 1
    return count
```
global count changes Python's upfront scan: it now knows every reference to count in this function means the module-level one, so there's no local shadow and no ordering problem.
Check for the non-global version of this same trap, which is more common in practice: a variable assigned only inside an if branch, then read after the if block, on a code path where that branch never ran:
```
def classify(n):
    if n > 0:
        label = "positive"
    print(label)  # UnboundLocalError when n <= 0
```
This has nothing to do with global scope — label is only conditionally assigned, and Python doesn't know that until the function actually runs. The fix is to give it a default before the branch, or add an else.

Two mistakes worth knowing about ahead of time

Adding global everywhere out of caution, including to functions that only read the variable. You only need global in a function that assigns to the name somewhere in its body. A function that only reads a module-level variable — never assigns to it — sees it just fine without any declaration at all. Sprinkling global on every function that merely mentions a shared name is a sign the scope model isn't fully clicked into place yet, and it tends to spread mutable shared state further than the program actually needs.

Assuming this means "the variable isn't defined yet" in a general sense, and hunting for an import order problem or a definition placed too late in the file. The variable is usually defined fine at module scope, well before the function runs. The problem isn't timing at the module level — it's that the function has its own, separate local variable of the same name, and that one hasn't been assigned yet inside this call.

A habit that prevents the confusion entirely

When a function needs to change something that lives outside it, default to passing values in and returning values out, rather than reaching into module-level state with global. It sidesteps this error category entirely, because there's no local/global name collision to trip over in the first place. Reserve global for the cases where shared mutable state is genuinely the right design — a counter tied to a long-running process, a cache, a small script where the overhead of threading values through every call isn't worth it — and even then, expect to type global explicitly the first time you assign to that name in a new function. Python won't infer the intent for you; the upfront scope scan happens the same way every time, regardless of what the variable meant one function ago.

If you'd like more posts like this sent straight to your inbox, subscribe to the newsletter.

Prefer to dig in yourself? The Python Essentials repo on GitHub has more free examples and exercises.

'Permission Denied' When Running a Script — It's Not Broken, It's Not Executable Yet

SystemCraftDev — Sun, 13 Sep 2026 02:33:24 +0000

The file is right there. It's not corrupted, and you're not missing a typo. Linux just hasn't been told this file is allowed to run — here's the one-line fix, and why sudo isn't it.

Adapted from the Command Line Essentials Companion Guide.

You write a script, save it, and try to run it:

$ ./deploy.sh
-bash: ./deploy.sh: Permission denied

The file is definitely there. cat deploy.sh prints it out fine. Nothing about the content is wrong. But the shell won't run it, and "Permission denied" sounds like something is badly broken — like the file itself is corrupted or off-limits. It isn't. It's missing one specific, easy-to-forget permission bit, and nothing else.

What's actually happening

Every file on a Linux (or macOS) system carries three separate permissions for three separate groups: the owner, the group, and everyone else. Each group can independently have read, write, and execute permission. ls -l shows this as a ten-character string:

$ ls -l deploy.sh
-rw-r--r-- 1 you staff 214 Sep 12 09:03 deploy.sh

Read that as three sets of three: rw- (owner: read, write, no execute), r-- (group: read only), r-- (everyone else: read only). Notice what's missing — there's no x anywhere in that string. The file is fully readable, which is why cat works and why the script's contents display just fine in an editor. But readable and executable are two completely different permissions, and creating a new file — via a text editor, touch, or copying one — doesn't grant execute permission by default. Nothing you did was wrong; that's simply not part of a new file's starting permissions.

Permission denied here isn't the system protecting something sensitive. It's the system accurately reporting that you haven't yet told it this particular file is meant to be run as a program.

The fix, step by step

Confirm this is actually the problem. Run ls -l on the file and look for an x in the owner's permission set (the first three letters after the leading -). If it's not there, this is exactly what's happening.
Add execute permission:

   chmod +x deploy.sh

This adds execute permission for everyone the file's other permissions already allow — for a typical personal script, that's enough. Confirm it worked:

   $ ls -l deploy.sh
   -rwxr--r-- 1 you staff 214 Sep 12 09:03 deploy.sh

Now there's an x in the owner's set.

Run it again the same way you did before:

   ./deploy.sh

No other change needed — the script's content was never the issue.

Two mistakes worth knowing about ahead of time

Reaching for sudo because "permission" sounds like an authority problem. sudo ./deploy.sh will not fix this — it re-runs the same command as another user, but the file still has no execute bit for anyone, so it fails the same way. sudo solves "you don't have rights to do this," not "this file hasn't been marked runnable yet." Those are genuinely different problems that happen to share the word "permission."

Forgetting the ./ and typing just deploy.sh. This produces a different error entirely — usually command not found — because the shell only searches directories listed in PATH for bare command names, and your current directory almost never is one of them. ./ explicitly means "run the file right here," which is what actually triggers the execute-permission check in the first place. If you're troubleshooting "permission denied" and you're not seeing that exact message, double check you're invoking the file the same way.

A habit that prevents the confusion entirely

Any time you write a new script you intend to run directly, chmod +x it in the same breath as saving it — before you ever try to run it the first time. Treat it as part of "finishing the script," not a fix you reach for after an error. Scripts you download or copy from elsewhere often already have execute permission preserved (or explicitly need it added once, on purpose) — but anything you create fresh with an editor starts without it, every time, and that's expected behavior, not a bug to work around.

If you'd like more posts like this sent straight to your inbox, subscribe to the newsletter.

Prefer to dig in yourself? The Command Line Essentials repo on GitHub has more free examples and exercises.

VS Code Is Running the Wrong Python — Here's Why the Terminal and IntelliSense Disagree

SystemCraftDev — Thu, 10 Sep 2026 02:12:12 +0000

Your venv is activated and IntelliSense resolves everything, but the terminal runs a different Python. Here's why VS Code tracks two separate Pythons, and the real fix.

Adapted from the VS Code Essentials Companion Guide.

You created a virtual environment, activated it, installed your packages — and VS Code still can't find them. Or the opposite: IntelliSense recognizes everything perfectly, but running the file in the terminal throws ModuleNotFoundError for a package you know is installed. Either way, it feels like VS Code is lying to you about something as basic as which Python it's using.

It isn't lying. It's just tracking two separate things that happen to look like one.

What's actually happening

VS Code has two independent ideas of "your Python," and they don't automatically sync:

The selected interpreter is what the Python extension uses for IntelliSense, linting, and Go to Definition. It's set explicitly — via the Status Bar or the Python: Select Interpreter command — and it sticks until you change it, regardless of what else happens in your project.

The terminal's active environment is whatever shell state is in effect when a terminal panel opens — usually whichever python resolves to on your PATH at that moment, or whatever a venv's activation script last set.

These can drift apart easily. Selecting an interpreter in the Python extension doesn't retroactively fix terminals you already had open. Opening a new terminal after switching interpreters usually auto-activates the matching environment — but "usually" is doing a lot of work in that sentence, and older terminal panels never get updated at all. The result: IntelliSense and the terminal can each be confidently, independently wrong about which Python is "the" Python, and neither one will tell you the other disagrees.

The fix, step by step

Check what IntelliSense thinks first. Look at the Status Bar at the bottom of the window — it shows the currently selected interpreter (something like Python 3.11.4 ('venv': venv)). If this is wrong, run:

   Python: Select Interpreter

and pick the correct one. This fixes IntelliSense, linting, and autocomplete — but not yet the terminal.

Check what the terminal thinks, separately. In an actual terminal panel, run:

   which python    # macOS/Linux
   where python    # Windows

Compare that path against the interpreter shown in the Status Bar. If they don't match, that's the whole problem — you have two different Pythons active in two different places.

Open a fresh terminal after fixing the interpreter. Close the old terminal panel and open a new one (Ctrl+Shift+`). A new terminal typically auto-activates the environment matching the currently selected interpreter — an already-open one will not retroactively update.
If the new terminal still doesn't auto-activate, activate the environment manually, the same way you would outside VS Code:

   source venv/bin/activate    # macOS/Linux
   venv\Scripts\activate       # Windows

Two mistakes worth knowing about ahead of time

Assuming "it works when I hover over the import" means the whole file will run correctly. IntelliSense resolving a package tells you the selected interpreter can see it — it says nothing about what a terminal's python file.py will use. These are genuinely separate checks, and passing one is not evidence for the other.

Installing a package a second time because "it's still not found." If pip install in a terminal reports success but the error persists, the terminal and the interpreter installing packages may not be the same Python. Check which python / where python before reinstalling anything — you may be about to install into an environment nothing is actually reading from.

A habit that prevents the confusion entirely

Whenever a project stops finding a package it should have, check both sides before touching anything: the Status Bar for what IntelliSense is using, and which python / where python in the terminal you're about to run code in. If those two don't match, you've found the entire bug already — no reinstalling, no deleting node_modules-style folders, no guessing. Open a new terminal, confirm it matches, and move on.

If you'd like more posts like this sent straight to your inbox, subscribe to the newsletter.

Prefer to dig in yourself? The VS Code Essentials repo on GitHub has more free examples and exercises.

'Column Must Appear in the GROUP BY Clause' — Why SQL Won't Let You Do That

SystemCraftDev — Tue, 08 Sep 2026 02:30:00 +0000

It isn't a syntax error and it isn't arbitrary. SQL is asking a question it genuinely can't answer on its own — and once you see that, the fix is obvious.

Adapted from the SQL Essentials Companion Guide.

You add one more column to a GROUP BY query, run it, and get this instead of results:

ERROR: column "products.name" must appear in the GROUP BY clause
or be used in an aggregate function

The query looked reasonable. Nothing is misspelled. But SQL is refusing to run it at all — not returning wrong data, just flatly declining. That refusal is the whole story: SQL isn't confused about syntax, it's telling you the question you asked doesn't have a single correct answer.

What's actually happening

SELECT category, name, COUNT(*) FROM products
GROUP BY category;

GROUP BY category collapses every row into one row per category. That's the point of grouping — dozens of individual product rows become a handful of category rows. But name is a per-row value, and each category groups together many different products, each with its own name. Once those rows are collapsed into one, which product's name is supposed to show up in the result?

There's no good answer, and SQL doesn't guess. Every column in the SELECT list has to be something that still makes sense after the collapse: either a column named in GROUP BY (one value per group, by definition), or the output of an aggregate function like COUNT(), SUM(), or MAX() (a value computed from the whole group, so it's well-defined no matter how many rows are in it). name is neither — it's a leftover from before the grouping happened, and the database won't silently pick one at random on your behalf.

The fix, step by step

Decide what you actually want name to mean in a grouped result. There are two real answers, and the fix depends on which one you meant:
If you wanted one row per product, not per category — you probably don't want to group by category at all, or you need category and name to define the group together:

   SELECT category, name, COUNT(*) FROM products
   GROUP BY category, name;

Now each group is one specific product within one category, so name has exactly one value per group.

If you genuinely only want one row per category, drop the column that doesn't belong at that level:

   SELECT category, COUNT(*) FROM products
   GROUP BY category;

If you wanted some representative name, not every name, wrap it in an aggregate that resolves the ambiguity on purpose — MIN(name), MAX(name), or, on databases that support it, STRING_AGG(name, ', ') to list all of them:

   SELECT category, STRING_AGG(name, ', ') AS product_names, COUNT(*)
   FROM products
   GROUP BY category;

Two mistakes worth knowing about ahead of time

Reaching for MAX() or MIN() just to make the error disappear. It works — the query runs — but if you didn't actually mean "the alphabetically last name," you've just replaced a clear error with a quietly wrong result. MAX()/MIN() are the right tool when you deliberately want a representative value, not a reflexive fix for an error you haven't read.

Assuming this error means the query is broken. It's the opposite: this is one of the few SQL errors that catches a real logical mistake before it produces bad data instead of after. A query that ran without complaint and silently picked one arbitrary name per group (which is what some databases, like older MySQL configurations, actually did before enforcing this rule) is far more dangerous than one that stops and asks you to clarify.

A habit that prevents the confusion entirely

Before adding any column to a GROUP BY query's SELECT list, ask what it's supposed to represent once rows collapse into groups: one value per group (put it in GROUP BY), a computed summary across the group (wrap it in an aggregate), or something else — in which case it probably means you're grouping by the wrong thing, or trying to answer two different questions in one query. The error isn't the database being pedantic. It's the one moment SQL forces you to answer a question you'd otherwise skip past.

If you'd like more posts like this sent straight to your inbox, subscribe to the newsletter.

Prefer to dig in yourself? The SQL Essentials repo on GitHub has more free examples and exercises.

Git Says You're in 'Detached HEAD State' — Here's What That Actually Means

SystemCraftDev — Fri, 04 Sep 2026 03:01:03 +0000

It reads like an error. It isn't one. Git is just telling you exactly where you are — and getting back to a branch takes one command, once you know why.

Adapted from the Git & GitHub Companion Guide.

You check out a specific commit to look at some old code, and Git prints this:

Note: switching to 'a3f92c1'.

You are in 'detached HEAD' state...

HEAD is now at a3f92c1 Fix login redirect

Nothing crashed. There's no red text, no error:, no fatal:. But "detached HEAD" sounds like something broke, so the instinct is to back out immediately and hope nothing was damaged. Nothing was.

What's actually happening

Normally, HEAD — Git's pointer to "where you currently are" — points at a branch, and that branch points at a commit. When you commit, the branch moves forward and HEAD moves with it, because HEAD is really just following the branch.

Checking out a specific commit directly (instead of a branch name) breaks that chain on purpose. HEAD now points straight at the commit, with no branch in between — "detached" from any branch. Git isn't warning you about damage. It's telling you, accurately, that if you commit right now, those commits won't belong to any branch — and will be effectively orphaned the moment you check out something else.

That's the entire risk: not corruption, just the possibility of doing new work in a spot Git won't automatically keep track of.

The fix, step by step

If you're just looking around — reading old code, checking what a file looked like at that commit — you don't need to do anything. Look, then check out main (or whatever branch you were on) when you're done:

   git checkout main

Nothing you did in detached HEAD state affects your branches at all.

If you started making changes and want to keep them, don't switch branches yet — that's the one action that can strand your work. Instead, turn your current position into a real branch:

   git checkout -b recovery-branch

This creates a new branch pointed at exactly where you are, commits and all, and reattaches HEAD to it. Nothing is lost.

If you made commits, switched away, and now can't find them, they're almost certainly still there — just unreferenced by any branch. git reflog shows every position HEAD has recently been at, including ones no branch points to:

   git reflog
   git checkout - recovery-branch <commit-hash>

Two mistakes worth knowing about ahead of time

Panicking and running something destructive. Detached HEAD state is not an error state — it's a completely normal, intentional part of how Git works, used constantly for things like checking out a tag or reviewing history. Running git reset --hard or anything else "just to be safe" is far more likely to lose work than the detached state itself ever was.

Making real changes without realizing you're still detached. This is the only version of this situation that can actually bite you — writing several commits' worth of work while detached, then checking out main without first branching off, which leaves those commits reachable only through git reflog (and reflog entries eventually expire). If you're not sure whether you're attached to a branch, git status tells you immediately — it says HEAD detached at <commit> right at the top when you're in this state, and names your branch when you're not.

A habit that prevents the scary version entirely

Before doing any real work after a git checkout <commit-hash>, get in the habit of checking git status first. If it says detached, branch off with git checkout -b before writing a single line — that one habit turns "I might have lost my commits" into "I never could have lost my commits" every time.

If you'd like more posts like this sent straight to your inbox, subscribe to the newsletter.

Prefer to dig in yourself? The Git & GitHub repo on GitHub has more free examples and exercises.

Why Your JavaScript Loop Logs the Same Value Every Time (And How to Fix It)

SystemCraftDev — Sat, 29 Aug 2026 04:18:47 +0000

It looks like a timing bug in setTimeout. It isn't. It's var's scope rules doing exactly what they're designed to do — and the fix is one keyword, once you know why.

Adapted from the JavaScript Essentials Companion Guide.

You write a loop that should print 0, 1, and 2, one second apart. Instead you get three 3s.

for (var i = 0; i < 3; i++) {
  setTimeout(() => console.log(i), 1000);
}
// 3
// 3
// 3

Nothing crashed. No error. The values just aren't what the loop clearly seems to promise. The first instinct is usually to suspect setTimeout itself — some kind of timing quirk, a race condition, maybe the callbacks are firing out of order. None of that is what's happening.

What's actually happening

var is function-scoped, not block-scoped. That means every single pass through the loop isn't creating a new i — there's exactly one i for the entire loop, shared by all three setTimeout callbacks. By the time any of those callbacks actually runs (a full second later, long after the loop has already finished all three iterations), i has already reached its final value: 3. All three callbacks look up the same variable, at the same moment, after the loop is long done — so they all see the same thing.

This isn't a bug in setTimeout, and it isn't a race condition. The loop runs to completion essentially instantly; the callbacks are what's delayed, and they're all reading from a single shared box that's already empty of the values you wanted by the time they check it.

The fix, step by step

Recognize the signature: a loop paired with a callback or setTimeout, where every output is identical — and it's always the final value the loop variable reached, never the first or the middle ones.
Change var to let:

   for (let i = 0; i < 3; i++) {
     setTimeout(() => console.log(i), 1000);
   }
   // 0
   // 1
   // 2

Understand why that one-word change works: unlike var, let is block-scoped — it creates a new i, freshly bound, for every single iteration of the loop. Each setTimeout callback closes over its own separate i, not one shared variable, so each one remembers the value it was handed at that specific point in the loop.
Confirm the fix conceptually, not just empirically — if you're not sure why swapping the keyword fixed it, you'll hit the same shape of bug again the next time it shows up somewhere let isn't the obvious first move (a closure inside a function, for example, not just a loop).

Two mistakes worth knowing about ahead of time

Assuming it's a setTimeout or async timing problem. This bug shows up identically with any deferred callback — event listeners, promises, array method callbacks assigned to run later — not just setTimeout. If you find yourself trying to "fix" it by reordering code or adding delays, that's a sign you're debugging the wrong layer. The loop already finished; nothing about timing changes what value is left behind.

Reaching for the old IIFE trick out of habit, without knowing why let alone is now enough. Before let existed, the standard fix was wrapping the loop body in an immediately-invoked function expression to force a new scope by hand. That still works, but it's solving a problem let already solves natively — if you're writing new code in 2026 and still reaching for an IIFE here, it's worth understanding that let's per-iteration binding was specifically designed to make that pattern unnecessary.

A debugging habit that works

Whenever a loop-plus-callback combination prints the same value repeatedly, don't start by investigating the callback's logic — check the loop variable's declaration first. var shared across every iteration versus let scoped fresh to each one explains this entire category of bug, and recognizing that signature immediately turns a confusing multi-minute debugging session into a one-word fix.

If you'd like more posts like this sent straight to your inbox, subscribe to the newsletter.

Prefer to dig in yourself? The JavaScript Essentials repo on GitHub has more free examples and exercises.