Skip to content

error-playbook.md

Latest commit

 

History

History
186 lines (132 loc) · 9.79 KB

error-playbook.md

File metadata and controls

186 lines (132 loc) · 9.79 KB
Raw

Error Playbook — Plain English Translations

Every error here follows the same format: 🔴 What it means in plain English 🧠 Most likely reasons (in order of how often they cause it) 🔧 What to try first

CORS Errors

"Access to fetch has been blocked by CORS policy" / "has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header"

🔴 Your website tried to talk to your backend, but the backend said "I don't know this address." 🧠 Most likely reasons:

  1. Your backend (n8n, Supabase, an API server) doesn't have your website's address on its approved list
  2. You're using www.yoursite.com but only yoursite.com is approved — or the other way around. One letter difference matters completely.
  3. You added the address but the wrong version (http vs https) 🔧 Go to your backend's CORS settings and add your exact website address. Add both the www and non-www versions if you're not sure which one you're sending from.

Important: CORS is not a one-time fix. Every new domain, subdomain, or staging URL needs its own entry. If you deploy to a new address, you'll hit this again.

Python Errors

NameError: name 'X' is not defined

🔴 Your code tried to use something that doesn't exist in this file — like trying to use a tool you left in another room. 🧠 Most likely reasons:

  1. You forgot to import it at the top of the file (from config import X or import X)
  2. You spelled it differently in two places — Python is case-sensitive, Token and token are different things
  3. It's defined in another file but was never brought into this one 🔧 Add the right import line at the top of the file. If it's in config.py, write: from config import X

ImportError: cannot import name 'X' from 'module'

🔴 You're asking for something that doesn't exist in that file — the name is either missing or spelled differently there. 🧠 Most likely reasons:

  1. The variable or function named X was never added to that module
  2. It exists but under a different name 🔧 Open the file you're importing from and check what names are actually defined there. Add X if it's missing. Copy the name exactly — no spelling changes.

SyntaxError: expected 'except' or 'finally' block

🔴 You started a try block but never finished it. In Python, try always needs a partner. 🧠 Most likely reason: A try: block without a matching except: block below it 🔧 Find the try: and add at minimum: except Exception as e: print(e) directly below it.

SyntaxError (general — "invalid syntax" or similar)

🔴 Python can't read your code at all. It couldn't even start running — something in the text itself is wrong. 🧠 Most likely reasons:

  1. Missing colon at the end of an if, for, while, def, or class line
  2. Mismatched brackets — opened ( but forgot to close it, or [ without ]
  3. Wrong indentation — Python is strict: use 4 spaces, not a mix of tabs and spaces
  4. A terminal command was pasted into the code file by accident (like python app.py appearing inside the code) 🔧 Look at the line number in the error. The real problem is often one line before that. Read that section out loud — incomplete Python sentences usually become obvious when you say them.

ValueError: invalid literal for int() with base 10

🔴 You tried to turn a word into a number but it isn't a number. 🧠 Most likely reason: A user typed "hello" or left the input empty where a number was expected 🔧 Add a check before converting: if not x.strip().isdigit(): print("Please enter a number")

ModuleNotFoundError: No module named 'X'

🔴 Your code is trying to use a package that hasn't been installed yet. 🧠 Most likely reasons:

  1. The package was never installed in this environment
  2. You're running the code inside Docker but installed the package on the server (outside the lunchbox) 🔧 Run pip3 install X. If you're using Docker, add X to requirements.txt and rebuild the container.

Docker Errors

Error response from daemon: No such container: [name]

🔴 Docker is looking for a machine that hasn't started yet, or that crashed before it could be found. 🧠 Most likely reasons:

  1. docker-compose up was never run, or failed before the container could start
  2. The container crashed during startup (often a missing environment variable or bad config) 🔧 Run docker-compose up (not docker-compose start) and watch what it prints. If it exits immediately, run docker-compose logs to read why it stopped.

I ran pip install on the server but the app still can't find the package

🔴 Your app lives inside a Docker container — a sealed lunchbox. You installed something on the table outside the lunchbox. The lunchbox doesn't know about it. 🧠 The cause: Docker containers are isolated. Server-level installs don't reach inside them. 🔧 Add the package name to requirements.txt. Then run: docker-compose down && docker-compose up --build. The --build flag repacks the lunchbox with the new ingredient inside.

Git Errors

Permission denied (publickey) / git@github.com: Permission denied

🔴 GitHub doesn't recognise your computer. It's asking for a secret handshake your computer hasn't set up yet. 🧠 Most likely reason: You're trying to use SSH but haven't generated or registered your SSH key with GitHub 🔧 Easiest fix — switch to HTTPS: get the HTTPS URL from GitHub (starts with https://, not git@), then run: git remote set-url origin https://github.com/your/repo.git HTTPS uses your username and password/token instead of SSH keys.

fatal: remote origin already exists

🔴 You tried to add a GitHub address but one is already saved. 🧠 Most likely reason: You ran git remote add origin twice, or the project already had a remote set 🔧 Update the existing address instead of adding a new one: git remote set-url origin https://github.com/your/repo.git

error: failed to push some refs to [URL]

🔴 GitHub has changes your computer doesn't know about yet. You can't send your version until you receive theirs first. 🧠 Most likely reason: Something changed on GitHub since you last pulled — could be a README edit, a file created through the GitHub website, or another machine pushing 🔧 Run git pull origin main first. Resolve any conflicts if it asks. Then git push again.

The authenticity of host 'github.com' can't be established

🔴 Your computer and GitHub have never talked before through SSH. Your computer is asking "is this really GitHub?" 🧠 Most likely reason: First-time SSH connection from this machine 🔧 Type yes and press Enter — it's a one-time confirmation. Or switch to HTTPS to avoid SSH entirely (see above).

Node / npm Errors

npm: command not found

🔴 npm isn't installed — or the terminal can't find it. 🧠 Most likely reason: Node.js isn't installed yet. npm comes bundled with Node.js — no Node means no npm. 🔧 Install Node.js from nodejs.org. Restart your terminal after installing. Then try the command again.

Cannot find module 'X' / Module not found: Can't resolve 'X'

🔴 Your code is trying to use a package that isn't downloaded in this project yet. 🧠 Most likely reason: The package is in the code but was never installed 🔧 Run npm install X (replace X with the package name from the error). Then try again.

ENOENT: no such file or directory, open '[path]'

🔴 Something is looking for a file that doesn't exist at that path. 🧠 Most likely reasons:

  1. The file was deleted or never created
  2. A folder name in the path is misspelled
  3. You're running the command from the wrong folder — the terminal's current location matters 🔧 Check the path shown in the error. Make sure every folder in that path exists. If the issue is your location, navigate to the right folder first (cd your-project-folder).

Supabase Errors

permission denied for schema [name]

🔴 Your app can see Supabase's front door but the office inside is locked. There are two separate locks and only one was opened. 🧠 Most likely reason: Exposing the schema and granting permissions are two separate steps. Most people do one and skip the other. 🔧 Run this in the Supabase SQL Editor:

GRANT USAGE ON SCHEMA yourschema TO anon, authenticated;
GRANT ALL ON ALL TABLES IN SCHEMA yourschema TO anon, authenticated;

Replace yourschema with your actual schema name (e.g. public, aridunu, etc.)

Data isn't loading / RLS blocking reads

🔴 Row Level Security is turned on but no rules were written for who can read or write. Default when RLS is on: nobody can do anything. 🧠 Most likely reason: RLS was enabled but policies were never created 🔧 In Supabase dashboard: Authentication → Policies → New Policy. Or in SQL Editor:

-- Allow anyone to read
CREATE POLICY "allow_read" ON your_table FOR SELECT USING (true);
-- Allow logged-in users to write
CREATE POLICY "allow_write" ON your_table FOR INSERT WITH CHECK (auth.uid() IS NOT NULL);

Environment Variable Errors

process.env.X is undefined / KeyError: 'X' / os.environ['X'] missing

🔴 Your code is looking for a secret key (API key, password, URL) that hasn't been set up in this environment. 🧠 Most likely reasons:

  1. The .env file exists on your computer but not on the server or Vercel where the app is actually running
  2. The variable name is spelled differently in the code vs the .env file — it's case sensitive (API_KEY and api_key are different)
  3. On Vercel: environment variables set locally don't automatically go to Vercel — they have to be added separately in Vercel's dashboard 🔧 Go to wherever your app is running (Vercel → Settings → Environment Variables, or your VPS .env file, or your docker-compose.yml env section) and add the variable there with the exact same name and value.