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.
ModuleNotFoundError: Module not found: Can't resolve '@/components/Header'
This error occurs when Next.js cannot resolve a module path, usually because the path alias is misconfigured in tsconfig.json or the file does not exist at the expected location. Fix it by verifying the paths mapping in tsconfig.json matches your directory structure and the target file exists.
TimeoutError: API resolved without sending a response for /api/users, this may result in stalled requests
This warning appears when a Next.js API route finishes execution without calling res.status().json() or res.end(). This typically happens when an async operation completes but the response is never sent, or when early returns skip the response. Fix it by ensuring every code path sends a response.
Error: Element type is invalid. Expected a string or a class/function but got: object. Check the render method of 'DynamicComponent'.
This error occurs when next/dynamic imports a module incorrectly, usually because the imported module uses a default export but dynamic() receives the module object instead. Fix it by ensuring the dynamic import returns the default export, or use a loading function to handle the import mapping.
InvalidImageError: Invalid src prop on next/image, hostname "cdn.example.com" is not configured under images in your next.config.js
This error occurs when the next/image component receives an external URL whose hostname is not listed in the images configuration in next.config.js. Next.js requires explicit allowlisting of external image domains for security and optimization. Fix it by adding the hostname to the images.remotePatterns array.
Error: ERR_TOO_MANY_REDIRECTS: Redirect loop detected in middleware
This error occurs when Next.js middleware creates an infinite redirect loop by redirecting to a URL that also triggers the middleware, which redirects again endlessly. Fix it by adding a condition to skip the redirect when the request already matches the target URL or by using a matcher config to exclude the redirect target.
Error: Error: Error serializing `.data` returned from `getServerSideProps`. Reason: `undefined` cannot be serialized as JSON.
This error occurs when getServerSideProps returns an object containing undefined values, which JSON.stringify cannot serialize. Next.js requires all props to be serializable. Fix it by replacing undefined values with null, filtering them out, or using JSON.parse(JSON.stringify(data)) to strip undefined fields before returning.
Error: Error: Custom 404 page could not be rendered. pages/404.tsx has an error.
This error occurs when your custom 404 page has a runtime or build-time error, causing Next.js to fail when rendering the not-found page. Common causes include importing server-only modules, using hooks incorrectly, or having syntax errors. Fix it by ensuring the 404 page is a simple static component with no data-fetching methods.
TypeError: TypeError: Cannot read properties of undefined (reading 'NEXT_PUBLIC_API_URL')
This error occurs when a Next.js environment variable is undefined because it is missing the NEXT_PUBLIC_ prefix for client-side access, or the .env file is not loaded. Server-side env vars are not bundled into client code. Fix it by adding the NEXT_PUBLIC_ prefix or moving the logic to a server component or API route.
TypeScriptError: Type error: Property 'email' does not exist on type 'User'.
This error occurs when TypeScript's strict type checking finds a property access that does not exist on the declared type. Next.js runs type checking during builds by default. Fix it by updating the type definition to include the missing property, or by correcting the property name to match the existing type.
Error: Error: invariant: static generation store missing in revalidateTag
This error occurs when revalidateTag or revalidatePath is called outside a server action or route handler context. These functions require the static generation store which is only available during server-side request processing. Fix it by calling revalidation functions inside a server action or API route handler.
Error: Error: Dynamic server usage: force-dynamic is not allowed in generateStaticParams
This error occurs when a statically generated page uses fetch with cache: 'no-store' or sets force-dynamic, but also exports generateStaticParams. These are contradictory: static generation requires cacheable data. Fix it by removing force-dynamic and using revalidation instead, or by removing generateStaticParams for truly dynamic pages.
Error: Error: Functions cannot be passed directly to Client Components unless you explicitly expose it by marking it with "use server".
This error occurs when a server function is passed as a prop to a client component without the 'use server' directive. In the App Router, functions crossing the server-client boundary must be explicitly marked as server actions. Fix it by adding 'use server' to the function or the file containing it.
Error: Error: Missing slot "modal" in parallel route. Expected to find a `@modal/page.tsx` or `@modal/default.tsx` file.
This error occurs when a Next.js parallel route slot is defined in the layout but the corresponding directory does not contain a page.tsx or default.tsx file. Parallel routes require each slot to have at least a default.tsx fallback. Fix it by adding a default.tsx file that returns null to the slot directory.
Error: Error: You are attempting to export "metadata" from a component marked with "use client", which is unsupported.
This error occurs when a page or layout marked with 'use client' exports a metadata object or generateMetadata function. Metadata in Next.js App Router must be defined in server components. Fix it by removing 'use client' from the page or extracting metadata to a separate server component layout.
Error: Error: Suspense boundary received an update before it finished hydrating. This caused the boundary to switch to client rendering.
This error occurs when a React Suspense boundary receives a state update before the server-streamed HTML finishes hydrating on the client. This forces React to discard the server HTML and re-render on the client, losing streaming benefits. Fix it by deferring state updates until after hydration completes using useEffect.
SyntaxError: Unexpected token o in JSON at position 1
This error occurs when Express tries to parse a malformed JSON request body. The client is sending invalid JSON or the Content-Type header is incorrect. Fix it by adding proper error handling middleware for JSON parse failures and validating the Content-Type header before parsing.
Error: req.session is undefined — session middleware not initialized
This error occurs when you access req.session before the express-session middleware has been registered, or when the session store fails to connect. Fix it by ensuring express-session is registered before your routes and that the session store connection is healthy.
TooManyRequestsError: Too Many Requests — rate limit exceeded
This error occurs when a client exceeds the configured request rate limit. The express-rate-limit middleware blocks further requests and returns a 429 status. Fix it by tuning the rate limit window and max values, adding a custom handler with a Retry-After header, and using a persistent store for multi-instance deployments.
TokenExpiredError: jwt expired
This error occurs when a JWT token's exp claim is in the past, meaning the token has expired. The jsonwebtoken library throws TokenExpiredError during verification. Fix it by implementing token refresh logic, returning a clear 401 response, and ensuring your token expiration times are appropriate for your use case.
MulterError: Unexpected field
This error occurs when the form field name in the multipart request does not match the field name configured in multer. The middleware expects a specific field name but receives a different one. Fix it by ensuring the client form field name matches the multer configuration exactly.
Error: socket hang up
This error occurs when the TCP connection is closed before the HTTP response is fully sent, typically because the client disconnected, a reverse proxy timed out, or an upstream service dropped the connection. Fix it by increasing timeout values, handling the close event on the request, and adding retry logic for upstream calls.
Error: connect ECONNREFUSED 127.0.0.1:5000
This error occurs when http-proxy-middleware or a similar proxy tries to forward a request to an upstream server that is not running or is unreachable. The TCP connection is refused because nothing is listening on the target port. Fix it by verifying the upstream service is running, adding health checks, and handling proxy errors gracefully.
SecurityError: Refused to execute inline script because it violates the following Content Security Policy directive
This error occurs when Helmet's Content Security Policy blocks inline scripts, styles, or external resources. The CSP header tells the browser to reject anything not explicitly whitelisted. Fix it by configuring Helmet's CSP directives to allow your legitimate sources using nonces, hashes, or specific domain allowlists.
TypeError: Cannot read properties of undefined (reading 'split')
This error occurs when code tries to access or parse req.cookies before the cookie-parser middleware is registered, leaving req.cookies undefined. The .split() call fails because it is called on undefined. Fix it by ensuring cookie-parser is registered before any route that accesses req.cookies.
NotFoundError: Cannot GET /api/users/profile
This error occurs when no route matches the requested path and method in Express, resulting in a default 404 HTML response. This usually means the route is misspelled, uses the wrong HTTP method, or the router is not mounted at the correct path. Fix it by adding a catch-all 404 handler and verifying your route definitions.
PayloadTooLargeError: request entity too large
This error occurs when the request body exceeds the size limit configured in Express's body-parser or express.json() middleware. The default limit is 100kb. Fix it by increasing the limit for routes that need larger payloads, adding a custom error handler for 413 responses, and validating payload sizes on the client side.
ServiceUnavailableError: Response timeout — service took too long to respond
This error occurs when an Express route handler takes longer than the configured timeout to send a response, typically due to a slow database query, external API call, or blocking operation. Fix it by setting appropriate timeouts, using the connect-timeout middleware, and ensuring long-running tasks are processed asynchronously.
Warning: Each child in a list should have a unique "key" prop
This warning fires when you render a list of elements without assigning a unique key prop to each item. React uses keys to track which items changed, were added, or removed. Fix it by adding a stable, unique key such as a database ID to each list element instead of using array indices.
Error: Too many re-renders. React limits the number of renders to prevent an infinite loop.
This error means a component keeps re-rendering endlessly because state is being set directly in the render body or an event handler calls setState immediately without user interaction. Fix it by ensuring setState calls are inside event handler callbacks or useEffect hooks, never at the top level of the component body.
TypeError: Cannot read properties of undefined (reading 'user')
This error happens when you call useContext and access a property but the component is not wrapped in the corresponding Context Provider. Without a Provider, the context value is the default (often undefined). Fix it by wrapping the consuming component tree in the correct Provider or by supplying a meaningful default value when creating the context.
Error: A component suspended while responding to synchronous input. This will cause the UI to be replaced with a loading indicator.
This error occurs when a React.lazy component is rendered without a Suspense boundary. React needs a Suspense fallback to display while the lazy-loaded chunk downloads. Fix it by wrapping the lazy component in a Suspense component with a fallback prop providing a loading state like a spinner or skeleton screen.
TypeError: Cannot read properties of null (reading 'focus')
This error occurs when you try to call a method on a ref whose current value is still null, typically because the DOM element has not yet mounted or was conditionally rendered away. Fix it by adding a null check before accessing ref.current, or by calling ref methods inside useEffect where the DOM is guaranteed to be ready.
TypeError: Cannot read properties of undefined (reading 'setState')
This error occurs when an event handler loses its `this` binding in a class component, making `this` undefined when the handler fires. In function components a similar issue arises when the handler function is stale or incorrectly referenced. Fix it by using arrow functions, binding in the constructor, or converting to a function component with hooks.
Warning: Failed prop type: Invalid prop `count` of type `string` supplied to `StatCard`, expected `number`.
This warning fires when a component receives a prop whose type does not match the defined PropTypes or TypeScript interface. The component may render incorrectly or produce subtle bugs. Fix it by passing the correct type from the parent, or by coercing the value at the component boundary and updating the type definitions to match actual usage.
Bug: Component displays stale data after state update when using React.memo or useMemo
This bug occurs when a memoized component or callback captures an outdated variable in a closure because its dependency array is missing the variable that changed. React skips re-rendering the memoized component since its deps appear unchanged. Fix it by including all referenced variables in the useMemo, useCallback, or React.memo comparison dependency arrays.
Warning: Can't perform a React state update on an unmounted component. This is a no-op, but it indicates a memory leak in your application.
This warning fires when an async operation (like a fetch or timer) completes after the component has unmounted and tries to call setState. The update is ignored but signals a memory leak. Fix it by returning a cleanup function from useEffect that cancels the pending operation, using an AbortController for fetch requests or clearing timers.
Warning: A component is changing an uncontrolled input to be controlled. This is likely caused by the value changing from undefined to a defined value.
This warning fires when an input starts as uncontrolled (value is undefined) and later becomes controlled (value is a string). React does not support switching between the two modes. Fix it by initializing the state to an empty string instead of undefined so the input is always controlled from the first render.
Error: Target container is not a DOM element.
This error fires when ReactDOM.createPortal or ReactDOM.render targets a DOM element that does not exist yet. The element may be missing from the HTML, the script may run before the DOM is ready, or the portal target ID is misspelled. Fix it by ensuring the target element exists in the HTML before the portal renders, or by deferring portal rendering to useEffect.
Error: This Suspense boundary received an update before it finished hydrating. This caused the boundary to switch to client rendering.
This error occurs when a Suspense boundary in a React 18 concurrent rendering app receives a state update before hydration completes, forcing React to discard the server HTML and re-render on the client. Fix it by deferring state updates with useTransition or startTransition, and by ensuring Suspense boundaries are properly placed around async content.
Error: connect ECONNREFUSED 127.0.0.1:5432
This error means Node.js cannot reach the server at the specified address and port, usually because the target service (database, API, etc.) is not running or is listening on a different port. Fix it by verifying the service is started and the host/port configuration matches.
Error: listen EADDRINUSE: address already in use :::3000
This error occurs when another process is already listening on the port your Node.js server is trying to bind to. Fix it by finding and stopping the conflicting process, choosing a different port, or ensuring your server shuts down gracefully so the port is released on restart.
Error: ENOENT: no such file or directory, open '/app/config/settings.json'
This error means Node.js tried to open a file that does not exist at the specified path. Common causes include wrong relative paths, missing files in Docker builds, or incorrect working directory assumptions. Fix it by using path.resolve with __dirname and verifying the file exists before reading.
RangeError: Array buffer allocation failed
This error occurs when Node.js tries to allocate a buffer larger than available memory or the V8 heap limit. Common causes include reading huge files into memory at once or concatenating unbounded data. Fix it by using streams for large data, setting appropriate memory limits, and validating input sizes.
MaxListenersExceededWarning: Possible EventEmitter memory leak detected. 11 'data' listeners added to [ReadStream]. Use emitter.setMaxListeners() to increase limit
This warning means you are adding more event listeners than the default maximum of 10 to a single EventEmitter instance, suggesting a memory leak. Fix it by removing listeners when they are no longer needed, using once() for one-time events, or restructuring code to avoid repeatedly attaching listeners.
Error: spawn /usr/bin/ffmpeg ENOENT
This error means Node.js tried to spawn a child process for a binary that does not exist at the specified path. The executable is either not installed, not in the system PATH, or the path is incorrect. Fix it by installing the required binary and verifying its path with which or where.
Error: ERR_STREAM_PREMATURE_CLOSE
This error occurs when a readable or writable stream is closed or destroyed before it finished processing all data. Common causes include client disconnections during file downloads, premature stream.destroy() calls, or piping errors. Fix it by handling the 'error' event on all streams and using pipeline() for safe piping.
Error: UNABLE_TO_VERIFY_LEAF_SIGNATURE
This error means Node.js cannot verify the SSL/TLS certificate presented by the server because the certificate chain is incomplete or the CA is not trusted. Fix it by providing the full certificate chain, setting the correct CA bundle, or ensuring your Node.js version has up-to-date root certificates.
Error: getaddrinfo ENOTFOUND api.example.com
This error means the DNS resolver could not find an IP address for the given hostname. Common causes include typos in the hostname, DNS server unavailability, or network configuration issues inside containers. Fix it by verifying the hostname, checking DNS configuration, and adding retry logic for transient failures.
Error: Cannot transfer object of unsupported type
This error occurs when you try to send a non-serializable object (like a function, class instance, or socket) to a Worker thread via postMessage. Worker threads communicate through structured clone, which only supports plain data. Fix it by serializing data to plain objects or JSON before sending.
Error: Worker 1 died with code 1, signal null
This error means a Node.js cluster worker process crashed and exited with a non-zero code. Common causes include unhandled exceptions, out-of-memory kills, or segmentation faults in native modules. Fix it by adding uncaughtException handling in workers and implementing automatic restart with crash loop detection.
Error: error:1C80006B:Provider routines::wrong final block length
This error occurs when decrypting data with an incorrect key, wrong IV, or corrupted ciphertext, causing the padding validation to fail. The cipher expects specific block alignment that does not match the input. Fix it by ensuring the encryption key, IV, and algorithm match between encryption and decryption.
Error: EACCES: permission denied, open '/var/log/app/server.log'
This error means Node.js does not have file system permissions to read, write, or execute at the specified path. Common causes include running as the wrong user, incorrect file ownership, or restrictive directory permissions. Fix it by adjusting file permissions, running as the correct user, or writing to a permitted directory.
Error: Nest can't resolve dependencies of the UserService (?). Please make sure that the argument UserRepository at index [0] is available in the UserModule context.
This error means NestJS cannot find a provider for a dependency listed in a service's constructor. The dependency is not registered in the module's providers array or is not exported from its originating module. Fix it by adding the dependency to providers or importing the module that exports it.
UnauthorizedException: Unauthorized
This error occurs when a NestJS guard returns false or throws, blocking access to a protected route. Common causes include missing or invalid JWT tokens, expired sessions, or misconfigured guard logic. Fix it by verifying the token is sent correctly in the Authorization header and the guard validates it properly.
BadRequestException: Validation failed (numeric string is expected)
This error occurs when a NestJS validation pipe rejects input that does not match the expected type or DTO constraints. Common causes include passing a string where a number is expected, missing required fields, or invalid enum values. Fix it by ensuring client input matches the DTO schema and pipe configuration.
Error: Cannot read properties of undefined (reading 'pipe')
This error occurs in a NestJS interceptor when the route handler does not return an Observable, typically because it returns void or a raw value instead. Interceptors expect next.handle() to return an Observable. Fix it by ensuring all intercepted handlers return a value and wrapping non-Observable returns with of().
Error: A circular dependency has been detected. Please, make sure that each side of a bidirectional relationship is decorated with "forwardRef()".
This error occurs when two or more NestJS modules or providers depend on each other, creating a circular import chain that the injector cannot resolve. Fix it by using forwardRef() on both sides of the circular dependency or by refactoring to extract shared logic into a separate module.
RequestTimeoutException: Request timeout: no response received within 30000ms
This error occurs when a NestJS microservice client sends a message but does not receive a response within the configured timeout. Common causes include the target service being down, slow processing, or mismatched message patterns. Fix it by verifying service connectivity, increasing timeouts for slow operations, and adding proper error handling.
Error: WebSocket is not open: readyState 3 (CLOSED)
This error occurs when NestJS tries to send a message through a WebSocket connection that has already been closed. Common causes include clients disconnecting unexpectedly, missing connection state checks, or sending after the server-side gateway is destroyed. Fix it by checking readyState before sending and handling disconnection events.
Error: Cannot determine a type for the "CreateOrderDto.items" property. Make sure you've added the appropriate decorators.
This error means NestJS Swagger cannot infer the type metadata for a DTO property because it lacks the required decorators. TypeScript metadata reflection does not preserve generic types like arrays. Fix it by adding @ApiProperty() with the type option and @Type() decorator from class-transformer.
QueryFailedError: relation "users" does not exist
This error means TypeORM tried to query a database table that has not been created yet because migrations have not been run. Common causes include forgetting to run migrations, synchronize being false in production, or migration files not being included in the build. Fix it by running pending migrations before starting the app.
Error: connect ECONNREFUSED 127.0.0.1:6379 - Redis connection to localhost:6379 failed
This error occurs when the NestJS Bull/BullMQ queue module cannot connect to Redis because the Redis server is not running or is unreachable at the configured host and port. Fix it by starting Redis, verifying the connection config, and adding connection retry logic in the queue module registration.
InconsistentMigrationHistory: Migration admin.0001_initial is applied before its dependency accounts.0001_initial on database 'default'
This error means a migration was applied out of order, usually because a custom user model was added after Django's admin migrations already ran. Fix it by resetting the migration state: clear the django_migrations table for the conflicting app, fake-apply the dependencies in order, then run migrate again.
TemplateDoesNotExist: TemplateDoesNotExist at /dashboard/ — dashboard/index.html
This error means Django cannot find the specified template file in any of its configured template directories. Fix it by verifying the TEMPLATES setting includes your app's directories, ensuring APP_DIRS is True, and checking that the template file path matches the string passed to render() exactly, including subdirectory names.
Forbidden (403): CSRF verification failed. Request aborted.
This error means Django's CSRF protection rejected a POST request because the CSRF token was missing or invalid. Fix it by including {% csrf_token %} in your form template, ensuring the CSRF middleware is active, and for AJAX requests, sending the token in the X-CSRFToken header extracted from the csrftoken cookie.
PermissionDenied: You do not have permission to perform this action.
This error means the authenticated user lacks the required permission for the requested action. Fix it by verifying the user has the correct permission assigned via Django's auth system, checking your permission_required decorator or has_perm calls, and ensuring the user's groups include the necessary permissions in the database.
IntegrityError: UNIQUE constraint failed: accounts_user.email
This error means a database insert or update tried to save a duplicate value in a column with a unique constraint. Fix it by validating uniqueness in the form or serializer before saving, using get_or_create() instead of create(), or handling the IntegrityError with a try/except block that returns a user-friendly error message.
N+1 Query Performance Issue: django.db.backends: (0.002) SELECT ... FROM "orders_order" WHERE "orders_order"."customer_id" = %s; args=(1,) [repeated 200+ times]
This performance issue occurs when Django executes a separate query for each related object in a loop, instead of fetching them all at once. Fix it by using select_related() for ForeignKey/OneToOne relationships or prefetch_related() for ManyToMany/reverse ForeignKey relationships in your queryset.
404 Not Found: GET /static/css/styles.css HTTP/1.1 404 Not Found
This error means Django cannot serve the requested static file because it is not collected or the static files configuration is incorrect. Fix it by running collectstatic, verifying STATIC_URL and STATIC_ROOT in settings, ensuring the file exists in the correct app's static/ directory, and using {% static %} template tags.
ValidationError: ['Enter a valid email address.']
This error means a form field's clean method or validator rejected the input data. Fix it by checking your form's clean methods return cleaned data correctly, ensuring custom validators raise ValidationError with user-friendly messages, and verifying the form is re-rendered with errors so users can see what went wrong.
MiddlewareNotUsed: ImproperlyConfigured: MIDDLEWARE contains 'myapp.middleware.RequestLogMiddleware' which does not define a __call__ method.
This error means your custom middleware class is missing the required __call__ method or was written for the old-style MIDDLEWARE_CLASSES format. Fix it by ensuring your middleware accepts get_response in __init__ and implements __call__ to process the request, following Django's new-style middleware pattern.
TypeError: send_welcome_email() got an unexpected keyword argument 'signal'
This error means your signal receiver function signature does not accept the keyword arguments Django passes automatically, including sender, signal, and instance. Fix it by adding **kwargs to your receiver function signature so it accepts all keyword arguments that Django's signal dispatch sends.
ConnectionError: Error 111 connecting to localhost:6379. Connection refused.
This error means Django cannot connect to the configured cache backend, usually Redis or Memcached. Fix it by verifying the cache server is running, checking the connection settings in CACHES, ensuring the correct host and port are configured, and adding a fallback to LocMemCache for development environments.
SuspiciousFileOperation: The joined path (/etc/passwd) is located outside of the base path component (/app/media).
This error means a file upload path tried to escape the MEDIA_ROOT directory, which Django blocks as a security measure. Fix it by sanitizing uploaded filenames, using Django's FileSystemStorage which handles path traversal protection, and never constructing file paths from user input without validation.
TypeError: can't compare offset-naive and offset-aware datetimes
This error means you are comparing a timezone-aware datetime with a naive datetime that has no timezone info. Fix it by consistently using django.utils.timezone.now() instead of datetime.datetime.now(), enabling USE_TZ = True in settings, and using timezone.make_aware() to convert any naive datetimes before comparison.
DoesNotExist: Product matching query does not exist.
This error means .get() was called on a queryset but no row matched the filter criteria. Fix it by using get_object_or_404() for views that should return a 404 page, wrapping .get() in a try/except block, or using .filter().first() which returns None instead of raising an exception when no match is found.
NoReverseMatch: Reverse for 'product_detail' with keyword arguments '{"slug": ""}' not found.
This error means Django's URL resolver cannot find a URL pattern matching the given view name and arguments. Fix it by verifying the URL pattern name matches the reverse call, ensuring the arguments satisfy the URL regex or path converter, and checking that the app's urls.py is included in the root URL configuration.
ValidationError: {"price": ["A valid number is required."]}
This error means a Django REST Framework serializer rejected the input data during validation. Fix it by ensuring the request data matches the serializer field types, checking that required fields are present, and verifying that custom validate methods return the validated data instead of silently discarding it.
CORS Error: Access to XMLHttpRequest at 'https://api.example.com/data/' from origin 'https://app.example.com' has been blocked by CORS policy.
This error means the browser blocked a cross-origin request because the Django backend did not include the correct CORS headers. Fix it by installing django-cors-headers, adding it to INSTALLED_APPS and MIDDLEWARE, and configuring CORS_ALLOWED_ORIGINS with the frontend's domain in settings.py.
TaskRevokedError: Celery task 'orders.tasks.process_payment' raised unexpected: kombu.exceptions.OperationalError: [Errno 111] Connection refused
This error means a Celery task could not connect to the message broker (Redis or RabbitMQ), or the task itself raised an unhandled exception. Fix it by verifying the broker is running and accessible, configuring task retries with exponential backoff, and adding proper error handling inside the task function.
ImportError: cannot import name 'auth_bp' from 'app.auth'
This error occurs when Flask cannot import a Blueprint because of a circular import or the Blueprint object name does not match what you are importing. Fix it by deferring the import, using an application factory pattern, or ensuring the Blueprint variable name in the module matches the import statement exactly.
OperationalError: (sqlite3.OperationalError) no such table: user
This error means SQLAlchemy cannot find the expected database table. It typically happens when you forgot to run migrations, the database file was deleted, or the model was defined after the tables were created. Fix it by running flask db upgrade or creating tables with db.create_all() inside the app context.
ExpiredSignatureError: Signature has expired
This error occurs when a JWT token presented to your Flask app has passed its expiration time. It typically means the client is using a stale token or the server's expiry window is too short. Fix it by implementing a token refresh endpoint, extending the token lifetime, or catching the exception and returning a proper 401 response.
TemplateNotFound: jinja2.exceptions.TemplateNotFound: index.html
This error means Jinja2 cannot locate the template file. Flask looks for templates in a 'templates' folder relative to the application or blueprint. Fix it by ensuring the template file exists in the correct templates directory, the folder is named exactly 'templates', and the path passed to render_template matches the file structure.
BuildError: werkzeug.routing.exceptions.BuildError: Could not build url for endpoint 'user_profile'
This error occurs when url_for() references an endpoint that does not exist or is missing a required URL parameter. It usually means the function name is misspelled, a blueprint prefix is missing, or a dynamic route parameter was not provided. Fix it by verifying the endpoint name matches the view function and all required parameters are passed.
RequestEntityTooLarge: 413 Request Entity Too Large
This error occurs when an uploaded file exceeds Flask's MAX_CONTENT_LENGTH setting, which defaults to unlimited but is commonly set low. The request is rejected before your handler runs. Fix it by increasing MAX_CONTENT_LENGTH to an appropriate limit, validating file size client-side, and handling the 413 error gracefully with a custom error handler.
CORSError: Access to XMLHttpRequest at 'http://localhost:5000/api/data' from origin 'http://localhost:3000' has been blocked by CORS policy
This error occurs when a browser blocks a cross-origin request because the Flask server does not include the required CORS headers. Fix it by installing and configuring Flask-CORS with the correct allowed origins, or by manually adding Access-Control-Allow-Origin headers to your responses using an after_request handler.
RuntimeError: The session is unavailable because no secret key was set
This error occurs when Flask tries to use the session but no SECRET_KEY is configured. Flask uses the secret key to cryptographically sign session cookies. Fix it by setting app.config['SECRET_KEY'] to a strong random value, ideally loaded from an environment variable rather than hardcoded in source code.
CommandError: alembic.util.exc.CommandError: Target database is not up to date
This error occurs when Alembic detects that the database schema is out of sync with the migration history. You typically hit it when running flask db migrate before applying pending migrations. Fix it by running flask db upgrade first to bring the database up to date, then generate new migrations.
ValidationError: marshmallow.exceptions.ValidationError: {'email': ['Not a valid email address.'], 'age': ['Not a valid integer.']}
This error occurs when incoming request data fails Marshmallow schema validation. The validation error dictionary maps field names to lists of error messages. Fix it by catching ValidationError in your route handler, returning a 422 response with the error details, and ensuring your frontend sends data in the format your schema expects.
RateLimitExceeded: 429 Too Many Requests: Rate limit exceeded
This error occurs when Flask-Limiter detects too many requests from a client within the configured time window. It protects your API from abuse but can block legitimate users if misconfigured. Fix it by adjusting rate limits, implementing per-user limits with proper key functions, and adding a custom 429 error handler with Retry-After headers.
WebSocketError: RuntimeError: You need to use a gevent or eventlet server for WebSocket support
This error occurs when Flask-SocketIO is used with a WSGI server that does not support WebSockets. The default Flask development server and Gunicorn without async workers cannot handle WebSocket connections. Fix it by running your app with eventlet or gevent, or by configuring Gunicorn with the eventlet worker class.
RuntimeError: RuntimeError: Working outside of application context
This error occurs when you access Flask objects like current_app, g, or db outside of a request or application context. Flask requires an active application context for these operations. Fix it by wrapping the code in with app.app_context(): or ensuring it runs inside a request handler, CLI command, or test fixture that provides the context.
OperationalError: kombu.exceptions.OperationalError: [Errno 111] Connection refused
This error occurs when a Celery worker or producer cannot connect to the message broker, usually Redis or RabbitMQ. The broker may not be running, the connection URL may be wrong, or a firewall is blocking the port. Fix it by verifying the broker is running, the CELERY_BROKER_URL is correct, and the broker port is accessible from your application.
SoftTimeLimitExceeded: celery.exceptions.SoftTimeLimitExceeded: SoftTimeLimitExceeded()
This error occurs when a Celery task exceeds its soft time limit. Celery raises SoftTimeLimitExceeded as an exception inside the task so you can perform cleanup. Fix it by catching the exception to save partial progress, optimizing the task to run faster, breaking it into smaller subtasks, or increasing the time limit if the work genuinely takes longer.
EncodeError: kombu.exceptions.EncodeError: Object of type datetime is not JSON serializable
This error occurs when a Celery task argument or return value contains a type that cannot be serialized with the configured serializer (default: JSON). Python datetime objects, SQLAlchemy models, and other complex types are not JSON-serializable. Fix it by converting arguments to JSON-safe types like strings, dicts, or IDs before passing them to tasks.
MaxRetriesExceededError: celery.exceptions.MaxRetriesExceededError: Can't retry app.tasks.send_email[abc123] max retries exceeded
This error occurs when a Celery task has failed and exhausted all configured retry attempts. The underlying error keeps recurring across retries, typically because of a persistent external service failure. Fix it by implementing exponential backoff, catching the MaxRetriesExceeded exception to handle the final failure gracefully, and adding a dead-letter mechanism for failed tasks.
WorkerLostError: celery.exceptions.WorkerLostError: Worker exited prematurely: signal 9 (SIGKILL) Job: 42
This error occurs when a Celery worker process is killed by the OS, usually because it exceeded memory limits (OOM killer) or hit the hard time limit. The task cannot catch this because SIGKILL terminates the process immediately. Fix it by reducing memory usage in tasks, increasing container memory limits, or setting task_acks_late so tasks are redelivered to a healthy worker.
DatabaseError: django_celery_beat.models.PeriodicTask.DoesNotExist / celery.beat.SchedulingError: schedule not found
This error occurs when Celery Beat cannot load or parse the periodic task schedule. It often happens when the schedule configuration references a task that does not exist, the schedule dict has invalid crontab syntax, or the Beat database is corrupted. Fix it by verifying task names match registered tasks, checking crontab syntax, and resetting the Beat schedule file if needed.
TypeError: get_current_user() missing 1 required positional argument: 'db'
This error occurs when a FastAPI dependency function signature does not match what the dependency injection system expects. The DI container cannot resolve a parameter because it is not declared as a Depends() sub-dependency. Fix it by wrapping nested dependencies with Depends() so FastAPI can resolve the full chain automatically.
CORSError: Access to fetch at 'http://localhost:8000/api/data' from origin 'http://localhost:3000' has been blocked by CORS policy
This error occurs when a frontend running on a different origin makes a request to your FastAPI backend and the server does not include the required CORS headers. Fix it by adding CORSMiddleware to your FastAPI app with the correct allowed origins, methods, and headers so the browser permits the cross-origin request.
OperationalError: sqlalchemy.exc.OperationalError: (psycopg2.OperationalError) SSL connection has been closed unexpectedly
This error occurs when the database connection in the session pool becomes stale or is closed by the server, but SQLAlchemy tries to reuse it. Fix it by configuring pool_pre_ping=True on your engine so SQLAlchemy tests each connection before using it, and ensure you properly close sessions after each request with a dependency that uses a finally block.
RuntimeError: RuntimeError: Task got bad yield: <coroutine object send_notification at 0x7f8b2c3a1d00>
This error occurs when a background task is defined as an async function but is not properly awaited, or when you pass a coroutine object instead of a callable to BackgroundTasks.add_task(). Fix it by passing the function reference and its arguments separately to add_task() instead of calling the async function directly.
WebSocketDisconnect: starlette.websockets.WebSocketDisconnect: 1000
This error occurs when a WebSocket client disconnects and the server tries to send or receive data on the closed connection without handling the disconnection. Fix it by wrapping your WebSocket receive/send loop in a try/except block that catches WebSocketDisconnect and performs cleanup instead of crashing.
HTTPException: 422 Unprocessable Entity: value is not a valid UploadFile
This error occurs when a file upload endpoint expects a multipart form field but receives the data in the wrong format, or the endpoint parameter is not correctly annotated with File() or UploadFile. Fix it by using the correct type annotation with File(...) as the default and ensuring the client sends the file as multipart/form-data.
HTTPException: 401 Unauthorized: Could not validate credentials
This error occurs when JWT token validation fails due to an expired token, wrong signing algorithm, mismatched secret key, or malformed token header. Fix it by verifying the secret key and algorithm match between token creation and validation, adding proper error handling for expired tokens, and returning clear error messages to help the client refresh credentials.
RuntimeError: RuntimeError: No response returned from ASGI application
This error occurs when custom middleware does not properly call the next middleware or return a response, breaking the ASGI chain. Fix it by ensuring your middleware calls call_next(request) and returns the response object. If using BaseHTTPMiddleware, the dispatch method must return the response from call_next.
MissingGreenlet: sqlalchemy.exc.MissingGreenlet: greenlet_spawn has not been called; can't call await_only() here
This error occurs when you use SQLAlchemy's synchronous ORM operations inside an async FastAPI endpoint with an async engine. The sync API calls await_only() but no greenlet context exists. Fix it by using AsyncSession with async-compatible query methods like session.execute(select(...)) instead of session.query(...).
ValidationError: pydantic.error_wrappers.ValidationError: 1 validation error for UserResponse - field required (type=value_error.missing)
This error occurs when the data returned by your endpoint does not match the response_model schema. FastAPI validates the response through Pydantic, and missing or mistyped fields trigger a ValidationError. Fix it by ensuring the returned data includes all required fields defined in the response model or by making optional fields truly Optional.
HTTPException: 429 Too Many Requests: Rate limit exceeded
This error occurs when your rate limiter blocks requests but is misconfigured, applying limits too aggressively or not distinguishing between authenticated and anonymous users. Fix it by properly configuring slowapi or a custom rate limiter with appropriate limits per endpoint, user-based keys, and clear Retry-After headers.
RuntimeError: RuntimeError: Event loop is closed
This error occurs when an async startup event or lifespan handler tries to use the event loop after it has been closed, typically because the async resource initialization fails and cleanup runs against a closed loop. Fix it by using FastAPI's lifespan context manager pattern to properly initialize and clean up async resources like database pools and HTTP clients.
ActiveRecord::PendingMigrationError: Migrations are pending. To resolve this issue, run: bin/rails db:migrate RAILS_ENV=development
This error means your database schema is out of sync with your migration files. Rails detected migrations that have not been applied yet. Run bin/rails db:migrate to apply pending migrations and update your schema. This commonly happens after pulling new code that includes database changes from teammates.
ActionController::RoutingError: No route matches [GET] "/api/v1/users"
This error means Rails cannot find a route matching the requested URL and HTTP method. Check your config/routes.rb file to ensure the route is defined with the correct path, HTTP verb, and namespace. Run bin/rails routes to see all available routes and compare them against the request URL.
Sprockets::FileNotFound: couldn't find file 'application.css' with type 'text/css'
This error occurs when the Rails asset pipeline cannot locate a referenced asset file. It usually means the file was deleted, renamed, or the manifest is misconfigured. Check your app/assets/stylesheets directory for the file and verify your application.css manifest directives point to existing files.
ActionController::UnpermittedParameters: found unpermitted parameters: :admin, :role
This error means your controller received parameters that are not listed in your strong parameters permit list. Rails blocks unpermitted params to prevent mass assignment attacks. Add the missing parameters to your permit call if they are safe, or remove them from the form if they should not be submitted.
ActionController::InvalidAuthenticityToken: Can't verify CSRF token authenticity.
This error occurs when a form submission or AJAX request does not include a valid CSRF token. Rails uses CSRF tokens to prevent cross-site request forgery attacks. Ensure your layout includes csrf_meta_tags, your forms use form_with, and your AJAX requests include the token in the X-CSRF-Token header.
Bullet::Notification::UnoptimizedQueryError: USE eager loading detected Post => [:comments]
An N+1 query occurs when your code loads a collection and then makes a separate database query for each item's associations. This drastically slows page loads as the number of records grows. Fix it by using includes, preload, or eager_load to batch-load the associated records in a single query.
ActiveModel::ForbiddenAttributesError: ActiveModel::ForbiddenAttributesError
This error occurs when you pass raw params to a model create or update method without going through strong parameters. Rails requires you to call permit on parameters before mass assignment to prevent unauthorized attribute changes. Wrap your params in a method that calls require and permit.
ActiveRecord::RecordNotSaved: Failed to save the record: a]before_save callback returned false
This error occurs when a before_save, before_create, or before_validation callback explicitly returns false or calls throw(:abort), which halts the save chain. Review your model callbacks to find which one is stopping the save and fix the condition or use throw(:abort) only when you genuinely want to prevent persistence.
ActiveJob::SerializationError: Unsupported argument type: Symbol
This error occurs when you pass an argument to an ActiveJob that cannot be serialized by the job serializer. ActiveJob uses GlobalID for models and JSON serialization for primitives. Symbols, procs, and complex objects cannot be serialized. Convert symbols to strings and pass simple types or GlobalID-capable models.
ActionCable::Connection::Authorization::UnauthorizedError: An unauthorized connection attempt was rejected
This error occurs when ActionCable rejects a WebSocket connection because the connect method in your connection class calls reject_unauthorized_connection. This typically means the user is not authenticated or the session cookie is not being sent with the WebSocket handshake. Verify your authentication logic in ApplicationCable::Connection.
Net::SMTPAuthenticationError: 535 5.7.8 Authentication credentials invalid
This error means Rails cannot authenticate with your SMTP server using the provided credentials. The username or password is incorrect, or the SMTP server requires an app-specific password or OAuth2 token. Verify your SMTP settings in config/environments and use Rails credentials to store sensitive values securely.
ActiveStorage::FileNotFoundError: ActiveStorage::FileNotFoundError
This error occurs when ActiveStorage cannot find the blob file in the configured storage service. The file may have been deleted from the storage backend, the storage configuration may be wrong, or the blob record exists in the database but the actual file is missing. Verify your storage.yml configuration and check file existence.
ActionController::UnknownFormat: ActionController::UnknownFormat: TurboStreamController#create is missing a template for this request format and target
This error occurs when a controller action receives a Turbo Stream request but has no corresponding turbo_stream template or respond_to block handling the format. Create a .turbo_stream.erb template or add format.turbo_stream to your respond_to block to handle Turbo Stream requests properly in your Rails controller.
Pundit::NotAuthorizedError: not allowed to update? this Article
This error means the current user does not have permission to perform the requested action according to your Pundit policy. Pundit checked the policy class for the resource and the method returned false. Review your policy file to ensure the authorization logic correctly grants access to the appropriate user roles.
Devise::MissingWarden: Devise could not find the `Warden::Proxy` instance on your request environment
This error occurs when Devise cannot find the Warden middleware in your Rack stack. It usually means you are trying to use Devise helpers outside of the standard Rails request cycle, such as in a standalone test or a Rake task. Ensure Warden middleware is loaded and use appropriate test helpers for Devise.
Redis::CannotConnectError: Error connecting to Redis on 127.0.0.1:6379 (Errno::ECONNREFUSED)
This error means your Rails application cannot connect to the Redis server. Redis may not be running, the connection URL may be wrong, or the server is overloaded. Start Redis with redis-server, verify the connection URL in your configuration, and check that the Redis port is accessible from your application server.
Rack::Timeout::RequestTimeoutException: Request ran for longer than 15000ms
This error means a request exceeded the configured Rack::Timeout threshold. Long-running requests block web server threads and degrade performance for all users. Move expensive operations to background jobs using Sidekiq or ActiveJob, optimize slow database queries, and add pagination to endpoints that return large datasets.
NoMemoryError: failed to allocate memory (NoMemoryError)
This error occurs when your Ruby process exhausts available memory. Common causes include loading too many records into memory at once, large file processing without streaming, and memory leaks from global caches or retained references. Use find_each for batch processing, stream large files, and monitor memory with tools like derailed_benchmarks.
ThreadError: deadlock; recursive locking (ThreadError)
This error occurs when a thread tries to acquire a lock it already holds, creating a deadlock. In Rails, this often happens with class-level mutable state accessed from multiple threads in a Puma multi-threaded server. Use Mutex correctly, avoid recursive locking, and prefer thread-local variables or Concurrent::Map for shared state.
ArgumentError: 'invalid_status' is not a valid status
This error occurs when you assign a value to an enum attribute that is not in the defined list of valid values. Rails enums only accept declared values and raise an ArgumentError for anything else. Validate the input before assignment or rescue the error and return a meaningful message to the user.
ActiveRecord::RecordInvalid: Validation failed: User must exist
This error occurs because Rails 5+ requires belongs_to associations to be present by default. When you create a record without setting the foreign key, the validation fails. Either provide the associated record, set optional: true on the belongs_to declaration, or ensure the foreign key is correctly assigned before saving.
ActiveRecord::StatementInvalid: PG::UndefinedColumn: ERROR: column "orders.status" does not exist
This error occurs when a scope or query references a database column that does not exist. It often happens when scopes reference columns from a different table without a proper join, or when a migration adding the column was not run. Verify the column exists in the database schema and add necessary joins to your scope chain.
ActiveRecord::AssociationTypeMismatch: Comment(#123) expected, got String(#456)
This error occurs when you assign the wrong type to a polymorphic association or any typed association. Rails expects an instance of the associated model class but received a different type. Ensure you assign model instances, not raw strings or IDs, and that your polymorphic type and ID columns are set correctly together.
ActiveRecord::StatementInvalid: PG::UndefinedColumn: ERROR: column posts.comments_count does not exist
This error occurs when you enable counter_cache on an association but the parent table does not have the required counter column. Rails expects a column named associations_count on the parent model table. Add the column with a migration and optionally reset counters for existing records using reset_counters.
ActiveSupport::MessageEncryptor::InvalidMessage: ActiveSupport::MessageEncryptor::InvalidMessage
This error occurs when Rails cannot decrypt an encrypted message, usually because the secret_key_base has changed or the encrypted data is corrupted. This affects encrypted cookies, sessions, and credentials. Ensure your secret_key_base is consistent across deployments and environments, and re-encrypt any data if the key has been rotated.
Turbo::StreamsChannel::Error: Turbo::StreamsChannel refused connection for unauthorized user
This error occurs when a Turbo Streams broadcast channel refuses the WebSocket connection because the user is not authorized. Hotwire uses ActionCable for real-time updates and requires proper channel authorization. Ensure your Turbo::StreamsChannel subscription is verified and your signed stream names match between the broadcast and subscription.
Importmap::Engine::Error: Could not find javascript module 'controllers/hello_controller' in importmap
This error occurs when importmap-rails cannot resolve a JavaScript module referenced in your code. The module is not pinned in config/importmap.rb or the file path does not match the pin name. Add the missing pin to your importmap configuration or verify the file exists at the expected path under app/javascript.
Error: Error connecting Stimulus controller: 'search' controller is not registered
This error occurs when Stimulus cannot find a registered controller matching the data-controller attribute in your HTML. The controller file may be missing, not imported in the controllers index, or named incorrectly. Ensure the file naming convention matches and the controller is properly registered with the Stimulus application instance.
ViewComponent::TemplateError: Could not find a template file or inline render method for ButtonComponent
This error occurs when ViewComponent cannot find a template file or an inline render method for your component class. ViewComponent looks for a matching template file in the same directory as the component class or expects a call method for inline rendering. Create the template file or define a call method in the component.
GraphQL::ExecutionError: Field 'user' doesn't accept argument 'id' of type 'String' (expected 'ID!'|)
This error occurs when a GraphQL query passes an argument with the wrong type. The schema expects a specific type like ID! but receives a String. Review your GraphQL type definitions and ensure arguments match the expected types. Use proper type coercion in your resolvers and validate input types in your schema.
Redis::CannotConnectError: Error connecting to Redis on 127.0.0.1:6379 (Errno::ECONNREFUSED) for Sidekiq
This error means Sidekiq cannot connect to Redis, which it uses as its job queue backend. Redis may not be running, the connection URL is incorrect, or the connection pool is exhausted. Start Redis, verify the REDIS_URL environment variable, and ensure your Sidekiq configuration has the correct Redis connection settings.
Sidekiq::JobTimeout: Job exceeded timeout of 25 seconds
This error occurs when a Sidekiq job takes longer than the configured timeout to complete. By default, Sidekiq Pro enforces a 25-second timeout per job. Optimize the job to run faster, increase the timeout for long-running jobs, or break the work into smaller jobs that each complete within the timeout window.
Sidekiq::RetryExhausted: Job retries exhausted after 25 attempts
This error occurs when a Sidekiq job has failed and been retried the maximum number of times without succeeding. After exhausting retries, the job moves to the Dead Job queue. Investigate the root cause of the failure, fix the underlying issue, and re-enqueue the job from the Dead queue or programmatically using the Sidekiq API.
JSON::GeneratorError: source sequence is illegal/malformed (JSON::GeneratorError)
This error occurs when Sidekiq tries to serialize job arguments to JSON but encounters data that cannot be converted, such as binary strings, circular references, or non-UTF-8 encoded text. Ensure all job arguments are JSON-serializable primitive types and convert binary data to Base64 or store it externally before passing to the job.
Sidekiq::Shutdown: Sidekiq worker killed due to excessive memory usage (RSS: 1.2GB)
This error means your Sidekiq process consumed too much memory and was killed. Memory leaks in Sidekiq jobs are often caused by accumulating objects in class variables, not releasing large data structures, or loading too many records without batching. Use tools like derailed_benchmarks to profile memory and ensure jobs release resources after processing.
Sidekiq::DeadSet::Error: Job moved to dead set after exhausting all retries
This error indicates a job was moved to Sidekiq's Dead Set after exhausting all retry attempts. Dead jobs remain in Redis for six months by default. Investigate the original error, fix the root cause, then re-enqueue the dead jobs using the Sidekiq Web UI or the DeadSet API programmatically.
BindingError: Error #01: Key: 'CreateUserRequest.Email' Error:Field validation for 'Email' failed on the 'required' tag
This error occurs when Gin's ShouldBindJSON fails because the incoming JSON payload is missing required fields or has invalid types. Fix it by adding proper validation tags to your struct, returning a clear 400 response with field-level error details, and ensuring your client sends the correct JSON shape.
RuntimePanic: runtime error: invalid memory address or nil pointer dereference in middleware
This panic occurs when a Gin middleware dereferences a nil pointer, typically by accessing a value from the context that was never set or by calling a method on an uninitialized dependency. Fix it by adding nil checks in your middleware, ensuring all dependencies are injected before the server starts, and using Gin's built-in recovery middleware.
RouteConflict: panic: wildcard segment ':id' conflicts with existing children in path '/users/:id'
This panic occurs at startup when Gin detects conflicting route definitions, such as a wildcard parameter segment and a static segment at the same path level. Fix it by restructuring your routes so that static paths are registered before or separately from parameterized paths, or by using route groups to avoid collisions.
JsonMarshalError: json: unsupported type: chan int
This error occurs when Gin tries to serialize a response containing a type that encoding/json cannot marshal, such as channels, functions, or complex numbers. Fix it by creating a dedicated response DTO struct that only contains JSON-serializable fields and mapping your internal types to it before calling c.JSON().
FileUploadError: http: request body too large
This error occurs when a file upload exceeds the maximum body size allowed by the server. Gin defaults to a 32 MB multipart form limit. Fix it by configuring MaxMultipartMemory on the Gin engine, validating file size and type before processing, and returning descriptive error messages to the client.
CORSError: Access to XMLHttpRequest at 'http://localhost:8080/api/data' from origin 'http://localhost:3000' has been blocked by CORS policy
This error occurs when your Gin backend does not include the proper Access-Control-Allow-Origin headers, causing the browser to block cross-origin requests from your frontend. Fix it by adding the gin-contrib/cors middleware with the correct allowed origins, methods, and headers for your frontend domain.
RateLimitExceeded: rate limit exceeded: 100 requests per minute
This error occurs when your rate limiting middleware blocks requests that exceed the configured threshold, but the implementation either panics on concurrent map access or returns unhelpful error messages. Fix it by using a thread-safe rate limiter like golang.org/x/time/rate and returning proper 429 status codes with Retry-After headers.
JWTAuthError: token is expired by 2h30m0s
This error occurs when a JWT token's expiration claim is past the current server time, or when the token signing key is mismatched between token creation and validation. Fix it by implementing proper token refresh logic, validating the signing method, and returning clear 401 responses with instructions for the client to obtain a new token.
WebSocketUpgradeError: websocket: request origin not allowed by Upgrader.CheckOrigin
This error occurs when the gorilla/websocket Upgrader rejects the WebSocket handshake because the request origin does not match the server's host. Fix it by configuring a CheckOrigin function on the Upgrader that validates allowed origins, and handle the upgrade error to return a proper HTTP response instead of silently failing.
TemplateRenderError: html/template: "index" is undefined
This error occurs when Gin tries to render a template name that was never loaded via LoadHTMLGlob or LoadHTMLFiles. It can also happen when the template file exists but contains a syntax error preventing parsing. Fix it by verifying your glob pattern matches the template files and that template names match the filenames used in c.HTML().
DatabaseConnectionError: dial tcp 127.0.0.1:5432: connect: connection refused
This error occurs when your Gin application cannot connect to the PostgreSQL database, typically because the database is not running, the connection string is wrong, or the connection pool is exhausted. Fix it by validating the connection at startup with db.Ping(), configuring pool settings, and implementing a health check endpoint.
RequestTimeout: context deadline exceeded
This error occurs when a request handler exceeds the context deadline, typically because a database query or external API call takes too long. Fix it by setting timeouts on your HTTP server, using context.WithTimeout for downstream calls, and returning a 504 Gateway Timeout response when the deadline is exceeded.
BindingError: code=400, message=Unmarshal type error: expected=int, got=string, field=age, offset=25
This error occurs when Echo's Bind method encounters a JSON field whose type does not match the struct definition, such as sending a string where an int is expected. Fix it by validating the bind error, returning structured 400 responses with field-level details, and using a custom validator for business rule checks.
MiddlewareError: echo: middleware returned an error: runtime error: index out of range [0] with length 0
This error occurs when an Echo middleware accesses a slice or array element at an index that does not exist, often from parsing headers or path segments that are empty. Fix it by adding bounds checks before accessing slice elements and returning structured error responses from middleware instead of letting panics propagate.
JWTError: code=401, message=missing or malformed jwt, internal=token contains an invalid number of segments
This error occurs when Echo's JWT middleware receives a token that is not a valid three-segment JWT string, typically because the Authorization header is missing the Bearer prefix or the token is truncated. Fix it by configuring the JWT middleware with proper token lookup, error handling, and a custom error response.
ValidatorError: code=500, message=Internal Server Error, internal=validator instance is not set
This error occurs when you call c.Validate() but have not registered a validator on the Echo instance. Echo does not include a built-in validator, so you must implement the echo.Validator interface and assign it to e.Validator. Fix it by creating a custom validator using go-playground/validator and registering it at startup.
FileServeError: open static/assets/logo.png: no such file or directory
This error occurs when Echo's static file handler cannot find the requested file at the specified filesystem path, typically because the working directory differs between development and production or the static file path is relative. Fix it by using embed.FS for production builds or configuring an absolute path to the static directory.
CORSError: Access to fetch at 'http://localhost:8080/api/data' from origin 'http://localhost:5173' has been blocked by CORS policy
This error occurs when your Echo backend does not include CORS headers, causing the browser to block cross-origin requests from your frontend dev server. Fix it by adding Echo's built-in CORS middleware with the correct allowed origins, methods, and headers for your frontend domain.
WebSocketError: websocket: close 1006 (abnormal closure): unexpected EOF
This error occurs when a WebSocket connection closes unexpectedly without a proper close handshake, typically because the client disconnected, a proxy timed out, or the server did not handle read errors gracefully. Fix it by implementing proper close handling, setting read deadlines with pong handlers, and distinguishing normal disconnects from real errors.
TemplateError: echo: renderer not registered
This error occurs when you call c.Render() in an Echo handler but have not registered a template renderer on the Echo instance. Echo does not include a built-in renderer, so you must implement the echo.Renderer interface and assign it to e.Renderer. Fix it by creating a template renderer that wraps html/template and registering it at startup.
DatabaseError: sql: database is closed
This error occurs when a query is executed on a database connection that has been closed, typically because db.Close() is called prematurely or the connection pool is misconfigured. Fix it by managing the database lifecycle properly with graceful shutdown, passing the db via dependency injection, and ensuring Close is only called when the application exits.
ContextDeadlineExceeded: context deadline exceeded (Client.Timeout exceeded while awaiting headers)
This error occurs when an Echo handler makes an outbound HTTP call that exceeds the client timeout, or when the request context deadline passes before the handler completes. Fix it by setting explicit timeouts on your HTTP client, propagating the request context to downstream calls, and returning meaningful timeout error responses.
RateLimitError: code=429, message=rate limit exceeded
This error occurs when Echo's rate limiting middleware blocks a request that exceeds the configured rate, but the implementation lacks proper client identification, store cleanup, or informative response headers. Fix it by using a token-bucket limiter with per-IP tracking, adding Retry-After headers, and implementing a cleanup goroutine to prevent memory leaks.
GoroutineLeak: goroutine count: 10247 — suspected goroutine leak
This error occurs when goroutines are spawned but never terminate, typically because they block on a channel, timer, or network call that never completes. The goroutine count grows unboundedly, consuming memory and eventually crashing the process. Fix it by using context cancellation to signal goroutines to stop and always providing an exit path from blocking operations.
ChannelDeadlock: fatal error: all goroutines are asleep - deadlock!
This fatal error occurs when all goroutines in the program are blocked waiting on each other, creating a circular dependency that can never be resolved. The Go runtime detects this and crashes the program. Fix it by using buffered channels, adding timeouts with select statements, or restructuring the communication pattern to avoid circular waits.
RaceCondition: WARNING: DATA RACE — Read at 0x00c0000b4010 by goroutine 8, Previous write at 0x00c0000b4010 by goroutine 7
This error is reported by Go's race detector when two goroutines access the same memory location concurrently without synchronization, and at least one access is a write. Fix it by using sync.Mutex, sync.RWMutex, atomic operations, or channels to synchronize access to shared state.
ContextCanceled: context canceled
This error occurs when an operation's context is canceled, typically because the HTTP client disconnected, a parent context timed out, or cancel() was called explicitly. Fix it by checking for context cancellation errors and handling them gracefully instead of treating them as unexpected failures. Log at debug level for client disconnects.
HTTPClientTimeout: net/http: request canceled (Client.Timeout exceeded while awaiting headers)
This error occurs when an outbound HTTP request exceeds the client's timeout before receiving response headers from the target server. The default http.Client has no timeout, so this happens when you set one but the server is too slow. Fix it by configuring appropriate timeout values, using context-based cancellation, and implementing retry logic with backoff.
JsonUnmarshalError: json: cannot unmarshal string into Go struct field Config.port of type int
This error occurs when encoding/json tries to decode a JSON value into a Go struct field of an incompatible type, such as a string into an int field. Fix it by either correcting the JSON source to send the right type, using json.Number for flexible numeric parsing, or implementing a custom UnmarshalJSON method on the struct.
SQLConnectionPoolExhausted: sql: database/sql: connection pool exhausted, all connections are in use
This error occurs when all connections in Go's database/sql connection pool are in use and a new query cannot acquire one before the timeout. Common causes include leaked connections from unclosed rows, too-low MaxOpenConns, or long-running transactions. Fix it by ensuring all rows and statements are closed, tuning pool settings, and adding connection timeout context.
FilePermissionError: open /var/log/app.log: permission denied
This error occurs when the Go process does not have filesystem permissions to read, write, or create the specified file. Common causes include running as a non-root user, incorrect directory ownership, or restrictive umask settings. Fix it by checking and setting proper file permissions with os.OpenFile, creating directories with os.MkdirAll, and handling permission errors gracefully.
UnrecoveredPanic: runtime error: invalid memory address or nil pointer dereference
This panic occurs when code dereferences a nil pointer, and no recovery mechanism is in place to catch it. In an HTTP server, an unrecovered panic in a handler goroutine crashes only that request, but in main or background goroutines it crashes the entire process. Fix it by adding recover in background goroutines and using middleware recovery in HTTP handlers.
TLSHandshakeError: tls: failed to verify certificate: x509: certificate signed by unknown authority
This error occurs when Go's HTTP client cannot verify the server's TLS certificate because it is self-signed, issued by an unknown CA, or the system's CA bundle is missing. Fix it by adding the CA certificate to the system trust store or configuring a custom TLS config with the CA certificate. Never disable TLS verification in production.