Settings Not Taking Effect

This page helps you resolve issues where settings.json configuration does not take effect as expected. For how configuration works, see Settings Files and Precedence and Settings, Environment Variables, and File Paths.

​

A setting does not take effect

• Restart required: some settings are marked "restart required" and only take effect after restarting Qoder CLI CN. Check against Settings, Environment Variables, and File Paths.
• Overridden by a higher-priority scope: check whether the same setting is set at a higher-priority level (local > project > user), causing the lower-priority value to be overridden.
• Command-line override: settings passed via --settings take precedence over all files and override same-named entries in them.

​

Override order recap

Settings merge from lowest to highest priority, with higher priority overriding lower:

1. Built-in defaults
2. User level (~/.qoder-cn/settings.json)
3. Project level (<project>/.qoder/settings.json)
4. Local level (<project>/.qoder/settings.local.json)
5. Command line --settings

Objects are deep-merged field by field; scalar values are replaced directly; some arrays (such as disable/exclude lists) are merged as a union.

​

Project settings are ignored

For security, project-level and local-level settings apply only when the current working directory is trusted. If settings.json inside a project has no effect at all:

• Confirm the current directory is trusted (security.folderTrust.enabled is on by default).
• When untrusted, only user-level settings are loaded. Trust for the current working directory is decided by the trust prompt at startup (choose "this session only" or "remember"; the latter is written to settings.local.json); you can also permanently trust frequently used directories via permissions.trustDirectories in global settings.
• /add-dir and --add-dir only add additional trusted directories for the current session; they cannot make an untrusted project directory trusted.

​

Format errors

• Settings files are JSON, with // and /* */ comments allowed (stripped before parsing). Common mistakes: trailing commas, mismatched quotes, unclosed brackets.
• A BOM at the start of the file is ignored automatically, but saving as UTF-8 without BOM is still recommended.
• Use your editor with the JSON Schema (schemas/settings.schema.json) for validation and completion.
• Fields must be placed under the correct group (such as ui.theme rather than top-level theme).
• Use the /settings panel to view and modify settings and avoid hand-written format errors.

​

Verify the effective configuration

• Run /settings to view the settings currently in effect.
• Diagnose layer by layer: temporarily remove the local-level/project-level file to confirm which layer introduced the problem.

​

Next steps

• How configuration works: Settings Files and Precedence.
• Full settings table: Settings, Environment Variables, and File Paths.
• Loading issues (memory/Skills/Agents not loaded): Memory, Skills, and Agents Not Loading.