Common ErrMsg Codes and Their Troubleshooting StepsError messages—ErrMsg—are the breadcrumbs software leaves when something goes wrong. They can be terse, cryptic, or downright helpful. This article groups common ErrMsg codes across environments (web apps, databases, operating systems, and APIs), explains what they mean, and provides step-by-step troubleshooting guidance and prevention strategies you can apply right away.
Why clear ErrMsg matter
Clear error messages speed debugging, reduce downtime, and improve user experience. A good ErrMsg points to the root cause, suggests remedial steps, and—if appropriate—includes context (request ID, timestamp, affected resource). Below, errors are organized by environment with practical steps.
Web applications
400 Bad Request
Meaning: The server cannot process the request due to malformed syntax or invalid parameters.
Troubleshooting:
- Reproduce the request in a tool like curl/Postman.
- Validate request headers, query parameters, and JSON payload against the API spec.
- Check server-side validation logic and deserialization errors.
- Look for malformed cookies or overly long headers.
Prevention:
- Use strong input validation and clear client-side error messages.
401 Unauthorized
Meaning: Authentication required or failed.
Troubleshooting:
- Verify authentication tokens (format, expiry, signature).
- Confirm client sends Authorization header.
- Inspect auth server logs and token introspection endpoints.
- Ensure clock skew isn’t causing token expiry issues.
Prevention:
- Provide refresh-token flows and clear user guidance to re-authenticate.
403 Forbidden
Meaning: Authenticated but not permitted to access the resource.
Troubleshooting:
- Check user roles/permissions and access-control lists.
- Inspect resource-level ACLs and route guards.
- Verify policy evaluation (e.g., RBAC/ABAC).
Prevention:
- Apply least privilege and explicit role mappings; return specific error codes for missing permissions.
404 Not Found
Meaning: Resource does not exist at the requested path.
Troubleshooting:
- Confirm correct URL and route matching.
- Check for trailing slashes, URL encoding, or case sensitivity.
- Inspect database lookups and object lifecycle (deleted vs. never created).
Prevention:
- Use helpful 404 pages that offer navigation or search.
408 Request Timeout
Meaning: Client didn’t complete the request in time.
Troubleshooting:
- Check client network stability and request size.
- Review server timeout settings and load balancer timeouts.
Prevention:
- Support resumable uploads and increase timeouts for long-running requests.
429 Too Many Requests
Meaning: Rate limits exceeded.
Troubleshooting:
- Check rate-limit headers (X-RateLimit-Remaining, Retry-After).
- Identify storms of automated requests or client misconfiguration.
- Inspect distributed rate-limiter state (Redis, in-memory).
Prevention:
- Implement exponential backoff and client-side throttling.
500 Internal Server Error
Meaning: Unhandled server-side exception.
Troubleshooting:
- Reproduce and capture stack traces from logs.
- Narrow by deploying or rolling back recent changes.
- Inspect dependency failures (databases, third-party APIs).
Prevention:
- Centralize error handling, add retries for transient failures, and create health checks.
Databases
Connection refused / could not connect
Meaning: Client cannot connect to the DB server.
Troubleshooting:
- Confirm host, port, credentials, and network ACLs.
- Check database listener and service status.
- Ensure connection pool size isn’t exhausted.
Prevention:
- Use connection pooling and proper resource limits.
Duplicate key / unique constraint violation (e.g., Err 1062 in MySQL)
Meaning: Attempting to insert/update violates a unique constraint.
Troubleshooting:
- Identify conflicting value and source of duplicate insert.
- Use SELECT to find existing record; inspect transactions for race conditions.
- Apply proper upsert semantics (INSERT … ON CONFLICT / REPLACE).
Prevention:
- Validate uniqueness client-side or use idempotency keys.
Deadlock detected
Meaning: Two or more transactions are waiting on each other.
Troubleshooting:
- Check DB deadlock logs for the victim/queries involved.
- Optimize transaction scope and ordering of operations.
- Reduce lock contention by using lower isolation levels if acceptable.
Prevention:
- Keep transactions short and consistent lock ordering.
Out of memory / query killed
Meaning: Query exhausted memory or exceeded resource limits.
Troubleshooting:
- Inspect query plans and indexes.
- Rewrite queries to be more selective or use pagination.
- Increase memory limits or adjust work_mem (Postgres) if safe.
Prevention:
- Monitor resource usage and optimize slow queries.
Operating systems & system-level ErrMsg
Permission denied (EACCES)
Meaning: Process lacks required filesystem or resource permission.
Troubleshooting:
- Check file owner, group, and mode bits (ls -l).
- Verify the process user identity and any security policies (SELinux, AppArmor).
- Use sudo or adjust permissions carefully.
Prevention:
- Run services with least privilege and document required access.
No such file or directory (ENOENT)
Meaning: Path or executable not found.
Troubleshooting:
- Verify the correct path and filename.
- Confirm environment variables like PATH.
- Check for race conditions where a file is removed before access.
Prevention:
- Use robust checks and fallbacks for filesystem operations.
Network is unreachable
Meaning: Host cannot be reached over the network.
Troubleshooting:
- Test routing and DNS (traceroute, dig).
- Verify firewall rules and interface status.
- Check upstream gateway and ISP issues.
Prevention:
- Use multiple network paths and health checks.
APIs & third-party services
502 Bad Gateway / 503 Service Unavailable
Meaning: Upstream service unavailable or overloaded.
Troubleshooting:
- Check upstream service health and latency.
- Inspect load balancer and proxy timeouts.
- Retry with exponential backoff for transient failures.
Prevention:
- Implement circuit breakers and graceful degradation.
504 Gateway Timeout
Meaning: Upstream did not respond in time.
Troubleshooting:
- Increase upstream timeouts temporarily to diagnose.
- Profile upstream processing and queries.
Prevention:
- Use caching and async processing for long tasks.
Invalid API key / 401 from provider
Meaning: Authentication with provider failed.
Troubleshooting:
- Verify API key validity, scopes, and usage limits.
- Confirm correct endpoint and headers.
Prevention:
- Rotate keys regularly and monitor usage.
Client-side errors (JavaScript, mobile)
Uncaught TypeError / ReferenceError
Meaning: Code is calling an undefined value or variable.
Troubleshooting:
- Reproduce in dev tools with source maps.
- Search for null/undefined references and add guards.
- Add unit tests for edge cases.
Prevention:
- Use static typing (TypeScript), linters, and runtime assertions.
CORS error
Meaning: Browser blocked cross-origin request due to policy.
Troubleshooting:
- Verify server sends correct Access-Control-Allow-Origin headers.
- Check for preflight (OPTIONS) handling and allowed methods/headers.
Prevention:
- Configure CORS on server for allowed origins and use credentials only when needed.
Troubleshooting workflow and tools
- Reproduce the error consistently. Start with a minimal request or action.
- Collect context: timestamps, request IDs, user ID, environment, full payloads, and headers.
- Check logs (application, system, network, and third-party). Use centralized logging (ELK, Splunk).
- Attach debugging tools: profilers, packet captures (tcpdump), DB slow-query logs.
- Isolate change: compare working and failing deployments or roll back recent changes.
- Implement and test a fix in staging, deploy gradually, and monitor.
Preventive practices
- Standardize error codes and include machine-readable error fields (code, message, details, request_id).
- Log contextual metadata and expose safe request IDs to users for support.
- Use retries with exponential backoff for transient failures, and circuit breakers for persistent downstream failures.
- Maintain runbooks and postmortems for recurring ErrMsg patterns.
- Practice chaos/ failure injection to discover weak points before they become incidents.
Example error-response structure (recommended)
{ "code": "USER_NOT_FOUND", "message": "User with id 12345 was not found.", "request_id": "req_20250903_abc123", "details": { "user_id": "12345", "timestamp": "2025-09-03T12:34:56Z" } }
Final notes
Clear ErrMsg shorten mean-time-to-repair and reduce user frustration. Focus on actionable messages, consistent formats, and observability to turn error breadcrumbs into a clear path for resolution.