Error Patterns
ErrPulse includes 45 built-in error patterns that match common error messages and provide plain-English explanations with fix suggestions. When an error event arrives, the server matches its message against these patterns and attaches the explanation to the error group.
How Pattern Matching Works
Each pattern has:
- Pattern — a regular expression matched against the error message
- Title — a short name for the error
- Explanation — what the error means in plain English
- Suggestion — how to fix it
Patterns are evaluated in order. The first match wins. If no pattern matches, the error is stored without an explanation.
Source: packages/core/src/explanations/patterns.ts
All Patterns
| Title | Pattern | Explanation | Suggestion |
|---|---|---|---|
| Null Reference Access | Cannot read propert(?:y|ies) of (undefined|null) | Your code tried to access a property on something that is undefined or null. This usually means a variable wasn't initialized, an API returned unexpected data, or an object was accessed before it was ready. | Add optional chaining (?.) or a null check before accessing the property. For example: obj?.property instead of obj.property. |
| Null Assignment | Cannot set propert(?:y|ies) of (undefined|null) | Your code tried to set a property on something that is undefined or null. | Check that the object exists before assigning to it. Initialize the object first if needed. |
| Not a Function | (\w+) is not a function | Your code tried to call something as a function, but it's not one. This often happens when a method name is misspelled, an import is wrong, or a callback wasn't passed correctly. | Check the spelling, verify the import, and make sure the value is actually a function before calling it. |
| Undefined Variable | (\w+) is not defined | Your code references a variable that doesn't exist in the current scope. This could be a typo, a missing import, or a scoping issue. | Check for typos in the variable name and ensure it's imported or declared before use. |
| Temporal Dead Zone | Cannot access '(\w+)' before initialization | A variable declared with let or const was used before its declaration was reached. JavaScript hoists the declaration but not the initialization. | Move the variable declaration before its first use, or restructure the code to avoid the circular dependency. |
| Constant Reassignment | Assignment to constant variable | Your code tried to reassign a variable declared with const. | Use let instead of const if you need to reassign the variable. |
| Stack Overflow | Maximum call stack size exceeded | A function called itself recursively without a proper exit condition, causing an infinite loop of calls until the stack ran out of space. | Add or fix the base case in your recursive function. Check for unintended circular calls between functions. |
| Syntax Error | Unexpected token | The JavaScript parser found a character it didn't expect. This usually means a missing bracket, comma, or quote somewhere. | Check the file around the reported line for missing or extra brackets, commas, semicolons, or quotes. |
| Module Not Found | Cannot find module '(.+)' | Node.js couldn't find the module you tried to import. Either the package isn't installed, the file path is wrong, or the module name is misspelled. | Run npm install to ensure all dependencies are installed. Check the import path for typos. |
| Invalid JSON | SyntaxError: .* is not valid JSON | Your code tried to parse a string as JSON, but the string isn't valid JSON. This often happens when an API returns HTML (like an error page) instead of JSON. | Log the raw response before parsing. Check that the API endpoint is correct and returning JSON. |
| Connection Refused | ECONNREFUSED | Your app tried to connect to a server that isn't accepting connections. The target service is either not running, listening on a different port, or blocked by a firewall. | Make sure the target service is running and listening on the expected host:port. |
| Connection Reset | ECONNRESET | The remote server abruptly closed the connection. This can happen due to server crashes, timeouts, or network issues. | Add retry logic with backoff. Check the remote server's logs for errors. |
| Connection Timed Out | ETIMEDOUT | The connection to the remote server took too long and was abandoned. The server might be overloaded or unreachable. | Increase the timeout, check network connectivity, or add retry logic. |
| DNS Lookup Failed | ENOTFOUND | The hostname couldn't be resolved to an IP address. The domain name is wrong or DNS is not working. | Check the hostname for typos. Verify DNS resolution is working. |
| Port Already in Use | EADDRINUSE | Your app tried to listen on a port that's already taken by another process. | Use a different port, or find and stop the process using that port: lsof -i :PORT |
| Fetch Failed | fetch failed|Failed to fetch | A network request failed completely. This usually means the server is unreachable, CORS blocked the request, or there's no internet connection. | Check that the URL is correct, the server is running, and CORS is configured if calling from a browser. |
| Network Error | Network request failed | A network request could not complete. The server may be down, the URL may be wrong, or the network may be unavailable. | Verify the target URL and network connectivity. |
| Client Error (4xx) | status code 4\d{2} | The server rejected the request due to a client-side issue — bad request data, missing auth, or accessing a resource that doesn't exist. | Check the request URL, headers, authentication, and body for correctness. |
| Server Error (5xx) | status code 5\d{2} | The server encountered an internal error while processing the request. | Check the server logs for the root cause. This is a backend issue. |
| Duplicate Entry | ER_DUP_ENTRY|duplicate key|unique constraint | A database insert or update violated a unique constraint — you're trying to insert data that already exists. | Use upsert/ON CONFLICT, or check for existing records before inserting. |
| Table Not Found | ER_NO_SUCH_TABLE|relation .* does not exist|no such table | The query references a database table that doesn't exist. | Run your database migrations. Check that the table name is spelled correctly. |
| SQL Syntax Error | ER_PARSE_ERROR|syntax error at or near | Your SQL query has a syntax error. | Check the SQL query for typos, missing commas, or incorrect keywords. |
| Database Busy | SQLITE_BUSY | SQLite couldn't acquire a lock because another connection is writing. This happens with concurrent writes. | Enable WAL mode, reduce write contention, or add retry logic. |
| Database Connection Failed | connection.*refused.*database|Can't connect to | Your app couldn't connect to the database server. The database might not be running or the connection string is wrong. | Verify the database is running and the connection string (host, port, credentials) is correct. |
| React Production Error | Minified React error #(\d+) | React threw an error in production mode. The error is minified — check the React error decoder for details. | Look up the error number at https://reactjs.org/docs/error-decoder.html for the full message. |
| Hydration Mismatch | Hydration failed|Text content does not match|did not match | The HTML rendered on the server doesn't match what React tried to render on the client. This causes the page to re-render completely. | Ensure server and client render identical output. Avoid using Date.now(), Math.random(), or browser-only APIs during initial render. |
| Invalid React Hook Call | Invalid hook call | A React hook was called outside of a function component, or you have multiple copies of React in your bundle. | Only call hooks at the top level of function components. Check for duplicate React versions with npm ls react. |
| Invalid React Child | Objects are not valid as a React child | You tried to render a plain object as a React child, which isn't allowed. | Convert the object to a string (JSON.stringify) or render its properties individually. |
| Missing React Key | Each child in a list should have a unique "key" prop | When rendering a list of elements, each item needs a unique key prop for React's reconciliation algorithm. | Add a unique key prop to each item. Use a stable ID, not array index. |
| ResizeObserver Loop | ResizeObserver loop | A ResizeObserver callback caused another resize, creating an infinite loop. This is usually harmless but noisy. | This is often safe to ignore. If it causes issues, debounce the resize handler. |
| JWT Error | jwt (expired|malformed|invalid) | The JSON Web Token is invalid — it may be expired, malformed, or signed with the wrong key. | Check token expiration, refresh the token, or verify the signing key matches. |
| Unauthorized | unauthorized|401 | The request lacks valid authentication credentials. | Ensure the auth token is present and valid. Check for expired sessions. |
| Forbidden | forbidden|403 | The server understood the request but refuses to authorize it. The user doesn't have permission. | Check user permissions and roles. Verify the user has access to this resource. |
| CORS Error | CORS|Access-Control-Allow-Origin|cross-origin | The browser blocked a request to a different origin because the server didn't include the right CORS headers. | Configure the server to send Access-Control-Allow-Origin headers. For development, use a proxy or cors middleware. |
| Out of Memory | heap out of memory|ENOMEM|JavaScript heap | The process ran out of available memory. This could be a memory leak or processing too much data at once. | Increase memory limit with --max-old-space-size, check for memory leaks, or process data in chunks. |
| High Memory Usage | memory usage.*threshold|high memory | The application's memory usage has exceeded the warning threshold. | Monitor for memory leaks. Consider restarting the process periodically or increasing available memory. |
| File Not Found | ENOENT|no such file or directory | Your code tried to access a file or directory that doesn't exist. | Check the file path for typos. Ensure the file exists before accessing it. |
| Permission Denied | EACCES|permission denied | The process doesn't have permission to access the file or resource. | Check file permissions. Run with appropriate user/group or fix file ownership. |
| Too Many Open Files | EMFILE|too many open files | The process has opened more files than the OS allows. This often indicates a file descriptor leak. | Close files after use. Increase the ulimit, or check for leaked file descriptors. |
| Operation Timed Out | timeout|timed out|ESOCKETTIMEDOUT | An operation took too long and was cancelled. The target service might be slow or overloaded. | Increase the timeout value, add retry logic, or investigate why the operation is slow. |
| Malformed URI | URIError|URI malformed | A URL encoding/decoding operation received an invalid URI. | Check the input for invalid characters. Use encodeURIComponent/decodeURIComponent correctly. |
| Invalid Array Length | RangeError.*Invalid array length | An array was created with an invalid length (negative or too large). | Check the value being used as the array length. |
| Type Error | TypeError | A value is not the type that was expected. This often means using the wrong method on the wrong data type. | Check what type the variable actually is (using typeof or console.log) and handle it appropriately. |
| Reference Error | ReferenceError | Your code references something that doesn't exist in the current scope. | Check for typos, missing imports, or variables used outside their scope. |
| Syntax Error | SyntaxError | The code has a syntax error that prevents it from being parsed. | Check for missing brackets, quotes, commas, or other syntax issues around the reported location. |
45 patterns — auto-generated from packages/core/src/explanations/patterns.ts.
TIP
Patterns are matched in order. More specific patterns (like "Cannot read properties of undefined") are checked before generic catch-alls (like "TypeError"). This ensures the most helpful explanation is always shown.