Debugging Guides
Distinguish symptoms from root causes, then verify the fix.
697 published
Page 3 of 7
ESLint: Parsing error on a valid file
Fix ESLint parsing errors by aligning the parser and parserOptions, adding TypeScript or JSX plugins, and matching the language version.
Git: Unable to create index.lock File exists
Fix Git index.lock errors by confirming no Git process is running, then removing a stale lock left by an interrupted command.
GitHub Actions Secret Not Found — Empty Environment Variable
Fix empty secrets in GitHub Actions by verifying the secret name, scoping it to the right environment, and handling fork and Dependabot restrictions.
GitHub Actions Invalid Workflow — YAML Syntax Error
Fix invalid workflow files by locating the YAML error, quoting special values, and validating locally before pushing.
GitLab CI Job Stuck — No Runner Matches the Tags
Fix jobs stuck at "This job is stuck" by aligning runner tags, checking shared-runner availability, and removing unmatched tag requirements.
Go: bufio.Scanner: token too long
Fix bufio.Scanner "token too long" by enlarging the buffer, splitting lines manually, or switching to bufio.Reader for unbounded input.
Go build fails with CGO_ENABLED=0 — cgo Code Not Available
Resolve cgo build failures during cross-compilation by isolating cgo files with build tags and choosing pure-Go implementations or a cross toolchain.
Go filepath vs path — Windows Path Breaks on Linux
Fix path handling that breaks across operating systems by using path/filepath for filesystem paths and path for URL or slash-delimited keys.
Go HTTP Handler Panic Closes the Connection
Fix Go net/http panics that abort a request by recovering in middleware, logging the stack, and returning a controlled 500 response.
Go interface conversion panic — Wrong Dynamic Type
Fix "interface conversion: interface {} is X, not Y" by using the two-value type assertion or a type switch instead of a single-value cast.
Go compile error: missing return at end of function
Fix the Go compiler error "missing return" when a function with a result type falls off the end of its body on some control-flow path.
Go: send or receive on a nil channel blocks forever
Diagnose a goroutine that hangs because it sends to or receives from a nil channel, and why the deadlock detector sometimes stays silent.
Go Nil Interface Method Call — Panic at Runtime
Fix "invalid memory address or nil pointer dereference" from calling a method on a nil interface by returning typed nils only when callers expect them.
Go Range Loop Variable Address Same — Shared Pointer Bug
Fix goroutines or closures capturing the same range variable address by copying the loop value per iteration or using Go 1.22 per-iteration semantics.
Go strconv.ParseInt invalid syntax — Numeric String Rejected
Fix strconv.ParseInt/Atoi invalid syntax errors by matching the parsed base and bit size to the input and trimming whitespace and separators first.
Go Test Panic: test timed out — Goroutine Deadlock
Diagnose "panic: test timed out" by reading the goroutine dump Go prints, finding the blocked channels or locks, and adding timeouts to waits.
Go: unexpected EOF while reading a stream
Diagnose Go "unexpected EOF" errors from truncated HTTP bodies, short files, or connection resets, and handle partial reads correctly.
Go compile error: imported and not used
Fix the Go compiler error "imported and not used" by referencing, aligning, or blank-importing packages that were added but never referenced in code.
Go vet: Printf format %d has arg of wrong type
Fix go vet printf warnings when format verbs do not match argument types, and understand why fmt still prints apparently correct output.
Go WaitGroup panic — Add Called After Wait / Negative Counter
Fix sync.WaitGroup misuse panics by calling Add before starting goroutines, never inside them, and rejecting a negative counter.
Go: x509: certificate signed by unknown authority
Fix the Go TLS error "x509: certificate signed by unknown authority" by trusting a private CA, correcting SNI, and avoiding blanket InsecureSkipVerify.
GraphQL Non-Null Field Returned Null — Error Propagation
Fix "Cannot return null for non-nullable field" by finding the resolver returning null, tracing error propagation, and aligning schema nullability.
HTTP 400 Bad Request — causes server-side
Diagnose HTTP 400 responses caused by malformed JSON, failing validation, mismatched content types, and header issues, using server logs and echoes.
HTTP 401 Unauthorized and WWW-Authenticate
Diagnose HTTP 401 Unauthorized by reading the WWW-Authenticate header, checking token format, and distinguishing expired tokens from missing credentials.
HTTP 403 Forbidden — authenticated but not allowed
Diagnose HTTP 403 Forbidden by separating authentication from authorization, checking roles, scopes, IP rules, and WAF blocks.
HTTP 404 Not Found — routing and deployment causes
Diagnose unexpected HTTP 404 in production from SPA fallback, trailing slashes, case sensitivity, and reverse-proxy path rewriting.
HTTP 405 Method Not Allowed — Wrong Verb
Fix 405 Method Not Allowed by matching the HTTP verb to the route, checking the server Allow header, and correcting client or proxy method handling.
HTTP 408 Request Timeout — Client Sent Too Slowly
Diagnose 408 Request Timeout by raising client-send timeouts, keeping connections alive, and preventing slow-loris style delays.
HTTP 414 URI Too Long
Fix HTTP 414 when query strings or URLs exceed server limits, and move bulky data from the URL into the request body.
HTTP 415 Unsupported Media Type — Content-Type Mismatch
Fix 415 Unsupported Media Type by sending the Content-Type the server expects and configuring the parser or framework to accept it.
HTTP 422 Unprocessable Entity — Validation Failed
Interpret 422 Unprocessable Entity as a semantic validation failure, read the field errors, and fix payload validation rather than the transport.
HTTP 500 Internal Server Error — finding the real cause
Diagnose HTTP 500 by correlating a request id with server logs, exposing stack traces safely, and ruling out downstream dependency failures.
HTTP Content-Length Mismatch — Truncated or Extra Response
Fix Content-Length mismatch errors by letting the stack set the header, avoiding manual writes, and streaming with chunked transfer instead.
HTTP If-None-Match and Weak ETags — Unexpected 200
Fix revalidation always returning 200 by generating stable ETags, using weak comparison correctly, and keeping Vary and Cache-Control consistent.
Java ArithmeticException: / by zero — Integer Division Trap
Fix "/ by zero" ArithmeticException by guarding integer divisors, distinguishing integer from floating-point division, and handling empty aggregates.
Java ArrayIndexOutOfBoundsException — Wrong Array Index
Fix ArrayIndexOutOfBoundsException by checking array length before access, using loop bounds < length, and preferring enhanced for or collections.
Java ConnectException: Connection refused
Diagnose Java java.net.ConnectException Connection refused by separating client, firewall, and remote-listener causes with telnet and netstat.
Gradle Daemon OutOfMemoryError — Build JVM Heap
Fix Gradle daemon OutOfMemoryError by raising daemon heap, stopping stale daemons, and separating build JVM memory from test JVM memory.
Java IllegalStateException: common triggers
Diagnose Java IllegalStateException from iterator misuse, stream reuse, and framework lifecycle violations, and find the real state invariant.
Java invalid target release — Wrong JDK or Compiler Flag
Fix "invalid target release: N" by installing the matching JDK, aligning maven.compiler.release, and checking JAVA_HOME.
Jackson UnrecognizedPropertyException — Unknown JSON Field
Fix Jackson UnrecognizedPropertyException by configuring FAIL_ON_UNKNOWN_PROPERTIES, adding @JsonIgnoreProperties, or matching the field names.
JVM: CodeCache is full. Compiler has been disabled
Fix the JVM "CodeCache is full" warning and falling throughput by sizing ReservedCodeCacheSize and finding code-generation leaks.
Lombok Annotations Not Processed — Getters Missing
Fix "cannot find symbol getX" with Lombok by enabling annotation processing, aligning Lombok with the JDK, and reordering the compiler plugin.
Maven NoSuchMethodError — Dependency Version Conflict
Fix NoSuchMethodError and NoClassDefFoundError from conflicting transitive dependencies by inspecting the dependency tree and pinning via dependencyManagement.
Maven BUILD FAILURE — surefire Test Mojo Failed
Read a Maven surefire failure to separate compilation errors, assertion failures, and environment issues, then rerun or target the failing test.
Java NumberFormatException — Unparseable Numeric String
Fix NumberFormatException by trimming input, matching the radix to Integer.parseInt, and using the correct parse method for decimals and large numbers.
Java SocketTimeoutException: Read timed out
Diagnose Java java.net.SocketTimeoutException Read timed out by measuring server latency, reviewing timeouts, and fixing pool or keep-alive reuse.
Spring Could Not Resolve Placeholder — Missing Property
Fix Spring "Could not resolve placeholder" by adding the missing property, checking profile-specific files, and verifying the property source order.
Java StringIndexOutOfBoundsException
Fix Java StringIndexOutOfBoundsException from substring and charAt calls with off-by-one indices or unchecked user input lengths.
Java UnsatisfiedLinkError: no library in java.library.path
Fix Java UnsatisfiedLinkError by locating native libraries, matching architectures, and setting java.library.path or system load paths.
JavaScript Array.sort — Numbers Sorted as Strings
Fix unexpected sort order by supplying a numeric comparator, since the default Array.sort converts elements to strings and compares lexicographically.
JavaScript Invalid Date — Parsing Produced NaN Time
Fix Invalid Date by using ISO 8601 input, checking Number.isNaN(date.getTime()), and avoiding browser-dependent date string parsing.
JavaScript NaN Comparisons — NaN !== NaN
Handle NaN correctly by using Number.isNaN, understanding that NaN is not equal to itself, and validating numeric input at the boundary.
Promise.all Rejects on the First Failure — Partial Results Lost
Choose between Promise.all, allSettled, and any by matching the failure policy you want, so one rejection does not discard useful results.
JavaScript TypeError — Cannot Convert undefined or null to Object
Fix "Cannot convert undefined or null to object" from Object.keys, spread, or destructuring by defaulting the input and validating at the boundary.
Kubernetes Deployment ProgressDeadlineExceeded
Fix ProgressDeadlineExceeded by checking rollout status, readiness probes, and image pull or scheduling failures that block progress.
Kubernetes FailedMount: unable to attach or mount volumes
Diagnose Kubernetes FailedMount by reading pod events, checking configmap and secret existence, and resolving node-level volume conflicts.
Helm Upgrade Failed — Release Stuck in pending-upgrade
Fix Helm upgrades stuck at "another operation in progress" by rolling back pending releases, using atomic and wait, and inspecting release history.
Kubernetes Ingress 404 — No Rule Matches the Host or Path
Fix Ingress 404s by matching the host header and path rules, checking the ingress class, and verifying backend service and port names.
Kubernetes Init:Error / Init:CrashLoopBackOff — Init Container Fails
Fix init container failures by reading its logs, checking its dependencies and commands, and verifying it exits zero before main containers start.
Kubernetes InvalidImageName — Malformed Image Reference
Fix InvalidImageName by correcting the registry, tag, or digest syntax and ensuring image substitution produces a valid reference.
Kubernetes NetworkPolicy Blocks Pod Traffic — Connection Timeout
Fix connection timeouts between pods by auditing NetworkPolicies, allowing the intended ingress and egress, and verifying with DNS and port tests.
Kubernetes OOMKilled — Container Exceeded Memory Limit
Fix OOMKilled by measuring real memory use, raising or right-sizing limits, and separating a leak from a transient spike.
Kubernetes PVC Pending — No StorageClass or Binding Failure
Fix a PVC stuck Pending by matching a StorageClass, checking access modes and capacity, and inspecting the provisioner events.
Kubernetes: exceeded quota for pods or requests
Diagnose Kubernetes quota errors when creating pods, and understand ResourceQuota limits on counts and aggregate CPU/memory requests.
Kubernetes Service Has No Endpoints — Selector Mismatch
Fix a Service with no endpoints by matching the selector to pod labels and confirming pods are Ready.
Kubernetes Pod Pending — Taint Not Tolerated
Fix unschedulable pods by adding a matching toleration, removing the taint, or adjusting node affinity and node selectors.
kubectl: unable to connect to the server
Fix kubectl "unable to connect to the server" by checking kubeconfig context, API server reachability, and credential expiration.
Kubernetes: x509 certificate has expired or is not yet valid
Fix Kubernetes x509 expiry errors from cluster CA rotation, kubelet certificates, and expired service-account or webhook certificates.
Linux: Permission denied even after chmod
Diagnose Linux Permission denied that persists after chmod by checking ownership, parent directories, mount options, and SELinux or AppArmor.
Linux: Segmentation fault (core dumped) debugging
Debug Linux segmentation faults with core dumps, gdb, and ulimit settings to locate the faulty instruction and memory access.
Linux: zombie processes (defunct) accumulating
Diagnose and reap Linux zombie processes by finding the parent that fails to call wait, and fixing signal handling or daemon design.
MongoDB: connection pool timeout waiting for available connection
Fix MongoDB connection pool timeouts by sizing maxPoolSize, finding connection leaks, and matching pool size to workload concurrency.
MongoDB: cursor not found (CursorNotFound)
Fix MongoDB CursorNotFound by understanding cursor timeouts, batch sizes, and noCursorTimeout, and why long-running iterations lose their cursor.
MongoDB Sort Exceeded Memory Limit — allowDiskUse Needed
Fix "Sort exceeded memory limit" by allowing disk use, adding a supporting index, and reducing the sorted result set.
MySQL ERROR 1406 — Data Too Long for Column
Fix MySQL 1406 by widening the column, validating input length, and making column characters match the UTF-8 byte budget.
MySQL Error 1054: Unknown column in field list
Fix MySQL error 1054 when a referenced column does not exist, covering typos, missing joins, aliases, and schema drift.
MySQL Error 1064: You have an error in your SQL syntax
Fix MySQL error 1064 by reading the near clause, checking reserved words, quoting, and the dialect differences that break generated queries.
MySQL ERROR 1071 — Specified Key Was Too Long
Fix MySQL 1071 by prefix-indexing long columns or reducing key byte length, since InnoDB limits the index key size.
MySQL Lost Connection / Read-Only — Failover or Restart
Diagnose "MySQL server has gone away" and read-only errors by distinguishing idle timeouts, restarts, and failover to a read-only replica.
MySQL ERROR 1055 — ONLY_FULL_GROUP_BY Rejects the Query
Fix MySQL 1055 by grouping or aggregating every non-aggregated selected column, and avoid disabling ONLY_FULL_GROUP_BY to hide invalid SQL.
Node.js child_process spawn ENOENT — Child Process Fails to Launch
Diagnose a Node.js child_process spawn ENOENT failure caused by a missing binary, a deleted cwd, or a PATH that differs between your shell and the service.
Node.js: child process killed with SIGKILL
Diagnose Node child processes killed with SIGKILL by distinguishing OOM kills, timeouts, and signal handling gaps in spawned services.
Node.js EMFILE: too many open files
Fix the Node.js EMFILE error when the process exhausts file descriptors through unclosed streams, watchers, or connection pools.
Node.js EPERM: operation not permitted
Resolve the Node.js EPERM error when writing, renaming, or deleting files on Windows and Linux due to locks, permissions, or antivirus interception.
Node.js ERR_HTTP_HEADERS_SENT — Headers Already Sent
Diagnose and fix ERR_HTTP_HEADERS_SENT in Node.js, raised when one request tries to set response headers a second time after they were already flushed.
Node ERR_INVALID_ARG_VALUE — Wrong Argument Type or Range
Trace ERR_INVALID_ARG_VALUE and ERR_INVALID_ARG_TYPE to the exact call site by reading the error code, syscall, and stack frame instead of guessing types.
Node.js ERR_INVALID_URL — TypeError Invalid URL
Fix the Node.js TypeError [ERR_INVALID_URL] when fetch or the WHATWG URL constructor rejects a relative, malformed, or protocol-less URL string.
Node.js ERR_WORKER_OUT_OF_MEMORY in worker_threads
Diagnose ERR_WORKER_OUT_OF_MEMORY when a Node worker thread exceeds its resourceLimits, and tune per-worker heap or reduce the workload.
Express PayloadTooLargeError — Request Body Over Limit
Resolve Express body-parser 413 Entity Too Large errors by matching the JSON and urlencoded limits to real payload sizes instead of blindly raising them.
Fetch AbortError Swallowed the Real Error in Retries
Prevent retry logic from treating the intentional AbortError from a timeout controller as a network failure, and preserve the original error cause.
Node EEXIST — File Already Exists When Writing
Fix Node EEXIST errors from mkdir, copyFile, and write-file-atomic by choosing the right flag and treating concurrent creation as normal.
Node.js ENOSPC: System Limit for Number of File Watchers Reached
Fix the inotify ENOSPC error on Linux when dev servers and editors exhaust file watchers, by raising fs.inotify.max_user_watches.
node-gyp Build Failed — Native Addon Cannot Compile
Repair node-gyp failures from native addons by checking Python, a C++ toolchain, node headers, and the gyp configuration that owns the build error.
Node Inspector Port In Use — Debugger Cannot Attach
Resolve "address already in use" and debugger attach failures by finding the process holding port 9229 and selecting a different inspector port.
Node ERR_PACKAGE_PATH_NOT_EXPORTED — Subpath Blocked by exports Map
Fix ERR_PACKAGE_PATH_NOT_EXPORTED and ERR_PACKAGE_PATH_NOT_DEFINED by reading a dependency exports map and importing only the public subpaths it declares.
node-sqlite3 SQLITE_BUSY — Database Is Locked
Fix intermittent SQLITE_BUSY database is locked errors from node-sqlite3 by enabling WAL mode, setting a busy timeout, and shortening write transactions.
yargs Unknown Argument — CLI Rejects a Valid Flag
Fix yargs strict-mode Unknown argument errors by declaring the flag, using coerce, and understanding camelCase and dashed aliases.
npm ci Fails — package.json and package-lock.json Out of Sync
Fix npm ci failures by regenerating the lockfile, committing it, and understanding why ci differs from install.
Open Redirect — Unvalidated Redirect Target
Fix open redirects by validating redirect targets against an allowlist, allowing only relative paths, and avoiding reflecting the request parameter.