Troubleshooting
This section documents common issues encountered while developing, running, and operating OneCMS.
Unlike setup guides, these topics focus on diagnosing and resolving problems that arise after the system is already running.
Issues may originate from frontend behavior, backend services, infrastructure configuration, or environment mismatches.
Before diving into specific problems, always start with basic inspection:
- Check browser DevTools (Console + Network tabs)
- Review server/container logs
- Verify environment variables and configuration
- Confirm whether the issue occurs in development, staging, or production
Categories
Runtime & UI Issues
Problems that occur while the application is running in the browser, such as loading states, rendering failures, hydration mismatches, and client-side errors.
Build & Deployment Issues
Issues that appear after building or deploying the application, including production-only failures, asset loading problems, and build configuration mistakes.
Environment & Configuration Issues
Misconfigurations related to environment variables, ports, domains, runtime settings, and platform-specific configuration.
Infrastructure & Hosting Issues
Docker, server, networking, and hosting-layer problems that affect application availability and connectivity.
Authentication & Authorization Issues
Login failures, token expiry problems, session inconsistencies, and permission-related access issues.
API & Backend Communication Issues
Failures involving API requests, service routing, gateway communication, CORS errors, and backend connectivity.
CMS Core Systems Issues
Platform-specific subsystem problems related to uploads, permissions, polling, analytics, feature registries, and AI workflows.
Performance & Stability Issues
Slow rendering, memory leaks, excessive re-renders, runtime freezes, and other stability-related concerns.
Each category contains problem-focused guides with symptoms, likely causes, and diagnostic steps.
ℹ️ Note
If a new issue is discovered, consider documenting it to help future engineers resolve it faster. Use the template below.
Template
Copy this template when documenting a new issue:
## <Issue Title>
:::info
**Category:** Runtime / Build / Environment / Infrastructure / Auth / API / CMS Core / Performance
**Applies to**: (Optional): Relevant frameworks, modules, or environments
**Quick Detection**: (Optional): One-line hint to quickly identify this issue
:::
### Symptoms
Describe what the engineer observes.
- Observable behavior
- Errors shown (if any)
- Environment where it occurs (dev / staging / prod)
- Whether issue is consistent or intermittent
### Likely Causes
List the most probable root causes.
- Cause 1
- Cause 2
- Cause 3
### What to Check
Concrete diagnostic steps.
- Logs to inspect
- DevTools panels to open
- Commands to run
- Config values to verify
### How to Fix
Actionable resolution steps.
- Config changes
- Code fixes
- Deployment steps
- Restart requirements
### Prevention Tips (Optional)
Best practices to avoid this issue in the future.
- Recommended patterns
- Guardrails
- Common pitfalls to avoid
### Related Issues (Optional)
Links to similar or commonly confused problems.