Production Error Guides
Step-by-step fixes for common production errors. Each guide walks through the full manual process, then shows how bugstack automates it in under 2 minutes.
TypeError: Cannot read properties of undefined (reading 'map')
This error occurs when you call .map() on a variable that is undefined, typically because an API response hasn't loaded yet or returned an unexpected shape. Fix it by adding a guard clause, optional chaining, or providing a default empty array before calling .map() on the data.
ReferenceError: document is not defined
This error occurs when server-side code tries to access the browser-only document object. In Next.js, components render on the server first where document does not exist. Fix it by wrapping document access in a useEffect hook or by using dynamic imports with ssr disabled.
UnhandledPromiseRejection: Unhandled promise rejection in async route handler
This error occurs when an async Express route handler throws an error that is not caught. Express does not natively catch promise rejections from async functions, causing the process to crash. Fix it by wrapping async handlers in a try-catch block or using an async error-handling wrapper middleware.
CORS Error: Access-Control-Allow-Origin header missing
This error occurs when a browser blocks a cross-origin request because the server response lacks the Access-Control-Allow-Origin header. Fix it by installing and configuring the cors middleware in your Express app, specifying allowed origins, methods, and headers for your frontend domain.
TypeError: Cannot read properties of null (reading 'useState')
This error occurs when React hooks are called outside a component or when multiple copies of React exist in the bundle. Common causes include calling useState in a regular function, having mismatched React versions, or incorrect bundler configuration. Fix it by ensuring hooks are only called inside React function components.
JavaScript heap out of memory: FATAL ERROR: CALL_AND_RETRY_LAST Allocation failed
This error occurs when Node.js runs out of heap memory, usually due to a memory leak from growing arrays, unclosed event listeners, or large data loaded without streaming. Fix it by identifying the leak source with heap snapshots, using streams for large data, and cleaning up event listeners properly.
TypeError: Cannot read properties of undefined (reading 'headers')
This error occurs when middleware tries to access req.headers but the request object is undefined, usually because middleware parameters are in the wrong order or a middleware function is invoked incorrectly. Fix it by ensuring your middleware uses the correct (req, res, next) signature and is passed as a reference, not called.
Hydration Error: Text content does not match server-rendered HTML
This error occurs when the HTML rendered on the server differs from what React generates on the client during hydration. Common causes include using Date.now(), browser-only APIs, or invalid HTML nesting. Fix it by ensuring deterministic rendering or using useEffect for client-only content and suppressHydrationWarning sparingly.
AttributeError: 'NoneType' object has no attribute 'id'
This error occurs when you access the .id attribute on a variable that is None, typically because a Django ORM query returned None instead of a model instance. Fix it by using get_object_or_404 to return a proper 404 response, or add a None check before accessing attributes on the query result.
ImportError: cannot import name 'app' from 'main'
This error occurs when Python cannot find the 'app' name in the 'main' module, usually due to circular imports, incorrect module paths, or the Flask app being defined with a different variable name. Fix it by restructuring imports to avoid circular dependencies or using an application factory pattern.
ValidationError: value is not a valid integer
This error occurs when a FastAPI endpoint receives data that does not match the Pydantic model's type annotations. For example, passing a string where an integer is expected triggers a 422 Unprocessable Entity response. Fix it by correcting the client payload or updating the Pydantic model to accept the actual data types.
OperationalError: could not connect to server: Connection refused
This error occurs when Django cannot connect to the PostgreSQL database server, usually because the server is not running, the host or port is wrong, or network rules block the connection. Fix it by verifying the database server is running, checking DATABASES settings in settings.py, and ensuring network connectivity.
KeyError: KeyError: 'user_id'
This error occurs when accessing a dictionary key that does not exist in the Flask request data, typically using request.form['user_id'] or request.json['user_id'] when the key is missing. Fix it by using request.form.get() or request.json.get() with a default value, and validate required fields explicitly.
RecursionError: maximum recursion depth exceeded
This error occurs when a function calls itself infinitely, exceeding Python's default recursion limit of 1000 frames. In Django, this commonly happens with overridden save() methods that call self.save(), circular signal handlers, or serializers with nested relationships. Fix it by breaking the cycle with conditional checks or using update() instead.
NoMethodError: undefined method 'name' for nil:NilClass
This error occurs when you call a method on a variable that is nil, typically because a database query returned no record. In Rails, calling .find_by or .first on a model can return nil. Fix it by using the safe navigation operator (&.) or adding a nil check before accessing methods on the result.
ActiveRecord::RecordNotFound: Couldn't find User with 'id'=999
This error occurs when ActiveRecord's find method is called with an ID that does not exist in the database. Rails raises RecordNotFound which renders a 404 in production but shows a stack trace in development. Fix it by rescuing the exception in the controller or using find_by with a nil check for custom error handling.
ArgumentError: wrong number of arguments (given 2, expected 1)
This error occurs when a Ruby method receives more arguments than its signature allows. In Rails, this commonly happens when calling a model method, callback, or service object with extra parameters it was not designed to accept. Fix it by updating the method signature to accept the correct number of arguments or correcting the call site.
PG::ConnectionBad: could not connect to server: No such file or directory
This error occurs when Rails cannot connect to PostgreSQL because the server is not running, the socket file is missing, or the connection parameters are incorrect. Fix it by starting PostgreSQL, verifying the socket path or switching to TCP connections, and checking your database.yml configuration matches your PostgreSQL setup.
runtime error: invalid memory address or nil pointer dereference
This error occurs when Go code dereferences a nil pointer, typically by accessing a field or calling a method on a nil value returned from a function. In Gin handlers, this often happens when database queries return nil results or when request binding fails silently. Fix it by checking for nil before dereferencing pointers.
runtime error: index out of range [0] with length 0
This error occurs when Go code accesses an index on an empty slice, such as items[0] when the slice has length 0. In Echo handlers, this commonly happens when a database query returns no results and the code accesses the first element without checking. Fix it by checking the slice length before accessing elements by index.