Safe error handling and logging

Design error handling that fails closed, tells clients only what they need, gives operators a correlation id and full context, and keeps logs free of secrets and injected lines.

● EasyFREEBy ·Design problem·15 min read·Beginner → Intermediate
error handlingfail closedlogginglog injectioninformation disclosurecorrelation id

01Understand the problem

✓What you will learn
  • Make security decisions fail closed when something throws
  • Split every error into a public part for the client and a private part for the logs
  • Prevent log injection and keep secrets out of log lines
  • Avoid enumeration through different error messages or status codes
◎Interview radar

What they probe: what happens when the policy service times out, what the client sees for an unexpected exception, how support finds the matching log line, and what must never be logged. Where candidates slip: catch { return true } in an access check, stack traces in production responses, User not found versus Wrong password, and logging the whole request including the Authorization header.

Error paths are where security code is least tested and most often wrong. A check that returns true from its catch block turns every outage of the policy service into an authorisation bypass. A default framework error page leaks the stack, library versions and SQL fragments. A log line built with string concatenation lets an attacker forge entries by putting a newline in their username.

  1. Security decisions (authentication, authorisation, signature checks) deny on any exception.
  2. Clients get a status code, a stable error code and a correlation id; never a stack trace, query or internal hostname.
  3. Logs get the correlation id, the error class, the cause chain and safe context; never passwords, tokens or full card numbers.
  4. Logs are structured (JSON), so user data cannot break a record or forge a new one.
  5. Authentication failures look the same whether the account exists or not.
Log itNever log it
Correlation id, route, status, latencyPasswords, even wrong ones (often a real password typed in the wrong field)
User id, tenant id, key id (not the key)Session ids, bearer tokens, API keys, cookies
Error class, message from your own code, cause chainFull card numbers (PCI DSS) or secrets embedded in URLs
Decision and reason for security events (denied: missing role)Full request bodies by default; health or special-category data

02Interfaces first

The contractts
export type PublicCode = "bad_request" | "unauthenticated" | "forbidden" | "not_found" | "conflict" | "rate_limited" | "internal";

/** An error your code raised on purpose. The message is for logs; publicMessage is safe to show. */
export class AppError extends Error {
  constructor(
    readonly status: number,
    readonly publicCode: PublicCode,
    readonly publicMessage: string,
    message: string,
    options?: { cause?: unknown },
  ) {
    super(message, options);
    this.name = "AppError";
  }
}

export interface ErrorBody {
  error: { code: PublicCode; message: string; correlationId: string };
}

export interface Log {
  error(msg: string, fields: Record<string, unknown>): void;
  warn(msg: string, fields: Record<string, unknown>): void;
  info(msg: string, fields: Record<string, unknown>): void;
}
iWhy a cause chain

Wrapping a low-level error (new AppError(503, ..., { cause: dbErr })) keeps the database error for the operator while the client only sees internal. Standard Error supports cause since ES2022, and most loggers print the chain.

03Fail closed, respond generically, log precisely

Fail closedts
// Wrong: any exception (timeout, bad JSON, null) grants access.
async function canEditBad(userId: string, docId: string): Promise<boolean> {
  try { return await policy.check(userId, "edit", docId); }
  catch { return true; }                                    // "don't block users during an outage"
}

// Right: the decision is false unless the check positively says true.
async function canEdit(userId: string, docId: string, log: Log): Promise<boolean> {
  try {
    const decision = await policy.check(userId, "edit", docId);
    return decision === true;                               // undefined, "true" or 1 are not true
  } catch (err) {
    log.error("policy check failed, denying", { userId, docId, err });
    return false;
  }
}
One error handler at the edgets
import { randomUUID } from "node:crypto";
import type { Request, Response, NextFunction } from "express";

/** Register last. Express recognises error middleware by its four parameters. */
export function errorHandler(log: Log) {
  return (err: unknown, req: Request, res: Response, _next: NextFunction): void => {
    const correlationId = (req as { id?: string }).id ?? randomUUID();
    const known = err instanceof AppError ? err : undefined;
    const status = known?.status ?? 500;
    const fields = {
      correlationId,
      method: req.method,
      route: req.route?.path ?? "unmatched",                // the pattern, not the raw URL with its query string
      status,
      err,                                                  // the logger serialises name, message, stack and cause
    };
    if (status >= 500) log.error("request failed", fields); else log.warn("request rejected", fields);

    const body: ErrorBody = {
      error: {
        code: known?.publicCode ?? "internal",
        message: known?.publicMessage ?? "Something went wrong. Quote the correlation id if you contact support.",
        correlationId,
      },
    };
    if (!res.headersSent) res.status(status).json(body);
  };
}

Login failures deserve their own care. The response must be identical for an unknown user and a wrong password, and so must the timing, which means running a password hash even when no user exists. The log, by contrast, records the precise reason for the security team.

Structured logging and uniform login failurespython
import json, logging, sys

class JsonFormatter(logging.Formatter):
    def format(self, record: logging.LogRecord) -> str:
        doc = {"ts": self.formatTime(record), "level": record.levelname, "msg": record.getMessage()}
        doc.update(getattr(record, "fields", {}))
        return json.dumps(doc, default=str)   # newlines inside values become \n, so one event stays one line

log = logging.getLogger("auth")
handler = logging.StreamHandler(sys.stdout)
handler.setFormatter(JsonFormatter())
log.addHandler(handler)

def login(username: str, password: str) -> dict:
    user = users.find(username)
    ok = hasher.verify(user.hash if user else DUMMY_HASH, password)   # same work whether or not the user exists
    if not (user and ok):
        log.warning("login failed", extra={"fields": {"reason": "no_user" if not user else "bad_password", "username": username}})
        return {"status": 401, "error": "Invalid username or password."}
    return {"status": 200}
▭On the whiteboard · Design choices4 points
01
decisions
true only on a positive result; every exception path returns deny and logs why
02
responses
status, stable code, generic message and correlation id; details stay server side
03
logs
JSON lines, correlation id, cause chain, explicit allow-list of fields
04
enumeration
same message, status and work for unknown user and wrong password

04Traps and tests

TrapWhat leaks or breaksFix
Framework debug mode in productionStack traces, source snippets, environment variablesSet NODE_ENV=production or DEBUG=False; test that a thrown error returns the generic body
String-built log linesUsername bob\nINFO login ok user=admin forges a recordJSON logs, or escape CR and LF
Logging the raw URLReset tokens and API keys in query stringsLog the route pattern; redact sensitive query parameters
Different status codes403 for an existing private document, 404 for a missing oneReturn 404 for both when existence itself is sensitive
Swallowed errorscatch {} hides an attack or a broken controlCatch narrowly, log, and rethrow or deny
Errors in the error handlerA logging failure crashes the process or returns a raw 500 pageKeep the handler simple and guard the logger call
!Logs are a data store

Anything you log is copied to log pipelines, vendors and backups, often with broader access than the production database. Treat a secret in a log as a leaked secret: rotate it, and fix the log statement.

vitestts
import { describe, it, expect } from "vitest";
import express from "express";
import request from "supertest";

function app(log: Log) {
  const a = express();
  a.get("/boom", () => { throw new Error("db password=hunter2 at 10.0.3.7"); });
  a.get("/nope", () => { throw new AppError(403, "forbidden", "You cannot do that.", "missing role editor"); });
  a.use(errorHandler(log));
  return a;
}

describe("errorHandler", () => {
  const lines: Record<string, unknown>[] = [];
  const log: Log = { error: (_m, f) => lines.push(f), warn: (_m, f) => lines.push(f), info: () => {} };

  it("hides internal details and returns a correlation id", async () => {
    const res = await request(app(log)).get("/boom");
    expect(res.status).toBe(500);
    expect(JSON.stringify(res.body)).not.toMatch(/hunter2|10\.0\.3\.7|at /);
    expect(res.body.error.correlationId).toMatch(/^[0-9a-f-]{36}$/);
  });
  it("passes through deliberate public messages", async () => {
    const res = await request(app(log)).get("/nope");
    expect(res.body.error).toMatchObject({ code: "forbidden", message: "You cannot do that." });
  });
  it("denies when the policy service throws", async () => {
    policy.check = async () => { throw new Error("timeout"); };
    expect(await canEdit("u1", "d1", log)).toBe(false);
  });
});

05Extensions, follow-ups, how to say it

  • Security events: send authentication, authorisation and admin events to a separate stream with longer retention for detection and audit.
  • Redaction as a library: a logger that redacts sensitive keys and token patterns by default beats reviewers spotting every call site (covered later in this track).
  • Fail open on purpose: some non-security features (recommendations, analytics) should fail open; write the choice down per dependency instead of letting it fall out of a catch block.
  • Error budgets: alert on spikes of 5xx and of denied decisions; a sudden rise in either is a signal.
Q1The policy service is down. Should the app fail open to stay available?+

Not for authorisation. Failing open hands access to whoever notices the outage. Keep availability with a local cache of recent decisions or a degraded read-only mode, and page someone.

Q2Why not show the exception message to the client if it is short?+

Messages from libraries contain hostnames, SQL, file paths and sometimes secrets. Only messages your code wrote for the client, such as AppError.publicMessage, are safe.

Q3How does support match a user report to a log line?+

The correlation id in the error body is also in every log line for that request, ideally propagated from the edge in a request id header so it spans services.

“How to say it in the room

"Security checks return deny unless they get a positive answer, and every exception path logs and denies. One error handler at the edge maps known errors to a status, a stable code and a safe message, and everything else to a generic 500, always with a correlation id. Logs are structured JSON with the cause chain and an allow-list of fields, so no tokens, passwords or raw URLs. Login failures are identical in message, status and timing."

Test yourself

An access check is written as `try { return await policy.allows(u, r) } catch { return true }`. The policy service starts timing out. What happens?

Finished this one?
Tick it and it shows as done on the roadmap and the course.