docs: add configuration validation details and troubleshooting guidance for librechat.yaml (#456)

pages/docs/configuration/dotenv.mdx

@@ -240,6 +240,20 @@ You may specify an **absolute path**, a **relative path**, or a **URL**. The fil
   ]}
 />
 
+### Configuration Validation
+
+By default, LibreChat will exit with an error (exit code 1) if the `librechat.yaml` configuration file contains validation errors. This fail-fast behavior helps catch configuration issues early in deployment pipelines and prevents running with unintended default settings.
+
+<OptionTable
+  options={[
+    ['CONFIG_BYPASS_VALIDATION', 'boolean', 'When set to `true`, the server will log a warning and continue starting with default configuration even if `librechat.yaml` has validation errors. This preserves the legacy behavior.', '# CONFIG_BYPASS_VALIDATION=true'],
+  ]}
+/>
+
+<Callout type="warning" title="Warning">
+Using `CONFIG_BYPASS_VALIDATION=true` is not recommended for production environments. It is intended as a temporary workaround while debugging configuration issues. Always fix validation errors in your configuration file.
+</Callout>
+
 ## Endpoints
 In this section, you can configure the endpoints and models selection, their API keys, and the proxy and reverse proxy settings for the endpoints that support it.
 

pages/docs/configuration/librechat_yaml/index.mdx

@@ -36,3 +36,15 @@ Future updates will streamline configuration further by migrating some settings
 Stay tuned for ongoing enhancements to customize your LibreChat instance!
 
 **Note:** To verify your YAML config, you can use the [YAML Validator](/toolkit/yaml_checker) or other online tools like [yamlchecker.com](https://yamlchecker.com/)
+
+<Callout type="error" title="Configuration Validation">
+**Important:** LibreChat will exit with an error (exit code 1) if the `librechat.yaml` configuration file contains validation errors. This fail-fast behavior helps catch configuration issues early and prevents running with unintended default settings.
+
+If you need to temporarily bypass validation (e.g., while debugging configuration issues), you can set the `CONFIG_BYPASS_VALIDATION=true` environment variable. This will log a warning and continue with default configuration, preserving the legacy behavior.
+
+```bash filename=".env"
+CONFIG_BYPASS_VALIDATION=true
+```
+
+> ⚠️ **Note:** Using `CONFIG_BYPASS_VALIDATION=true` is not recommended for production. Fix your configuration errors instead.
+</Callout>

pages/docs/configuration/librechat_yaml/setup.mdx

@@ -39,3 +39,36 @@ services:
 ```bash filename="Restart the containers"
 docker compose up
 ```
+
+## Troubleshooting
+
+### Server Exits Immediately on Startup
+
+If your server exits immediately after starting with exit code 1, this is likely due to configuration validation errors in your `librechat.yaml` file.
+
+**To diagnose the issue:**
+
+1. **Check the server logs** for validation error messages:
+   ```bash filename="View Docker logs"
+   docker compose logs api
+   ```
+
+2. **Validate your YAML syntax** using the [YAML Validator](/toolkit/yaml_checker) or tools like [yamlchecker.com](https://yamlchecker.com/)
+
+3. **Common validation errors include:**
+   - Invalid YAML syntax (incorrect indentation, missing colons, etc.)
+   - Unknown configuration keys or typos in property names
+   - Invalid values for specific configuration options
+   - Missing required fields
+
+**Temporary workaround:**
+
+If you need to start the server urgently while debugging configuration issues, you can bypass validation by setting:
+
+```bash filename=".env"
+CONFIG_BYPASS_VALIDATION=true
+```
+
+<Callout type="warning" title="Warning">
+Using `CONFIG_BYPASS_VALIDATION=true` will cause the server to log a warning and continue with default configuration. This is not recommended for production use. Always fix the validation errors in your configuration file.
+</Callout>

pages/docs/remote/docker_linux.mdx

@@ -212,6 +212,12 @@ cache: true
 
 Exit the editor with `CTRL + X`, then `Y` to save, and `ENTER` to confirm.
 
+<Callout type="info" title="Configuration Validation">
+LibreChat will exit with an error (exit code 1) if your `librechat.yaml` file contains validation errors. This fail-fast behavior ensures configuration issues are caught early in deployment.
+
+Before deploying, validate your configuration using the [YAML Validator](/toolkit/yaml_checker). If your CI/CD pipeline starts the server, it will fail fast on invalid configuration, preventing deployments with misconfigured settings.
+</Callout>
+
 #### Environment (.env) File
 
 The default values are enough to get you started and running the app, allowing you to provide your credentials from the web app.