Configuration Troubleshooting
Configuration Troubleshooting
Confirm file ownership, TOML shape, process location, precedence, status, and resolved paths before retrying.
.config/custy/config.tomlCategory
Quick Command
locate -> parse -> resolve -> validate path -> restartScope of This Pageâ
Use this page to diagnose shared TOML loading, precedence, caching, working directory, and path-resolution behavior. Use a command-specific guide when the configuration file resolves correctly but one invocation still rejects or misuses a value.
Fast Checksâ
git status --short --branch
custy --no-banner validateConfirm the current directory contains the intended .config/custy/config.toml
and configured project source before diagnosing an individual property.
Common Symptoms
Information
| Config file not found | Run from the intended project root or initialize the project-owned resources. A missing file loads as an empty configuration and resolvers use built-in defaults. |
|---|---|
| Invalid TOML | Correct the first TOML parser location. Check quotes, arrays, table headers, duplicate keys, and nesting below tool.custy. |
| A property appears ignored | Check the full path, CLI override, generated/default status, and whether the property is active, loaded-only, reserved, mismatch, or experimental. |
| An old value remains | The shared ConfigLoader is cached once per process. End the current Custy process and run a new invocation after saving the file. |
| A relative path resolves incorrectly | Resolve it from the process working directory or use an explicit path supported by the selected option. |
| Configured project source error | An explicit tool.custy.project.project_source must resolve to an existing directory. Use auto for runtime detection; a missing app/ directory is not an error in automatic mode. |
| Configured version target error | An explicit tool.custy.cli.paths.version_file must resolve to an existing file. Use auto to detect supported metadata or to allow a tag-only project. |
| Generated setting has no effect | Presence in the template is not proof of active consumption; use the property reference's implementation-status column. |
Resolution Checklist
- Identify the command option and exact TOML path.
- Remove assumptions about aliases or similarly named tables.
- Check whether a non-
NoneCLI value overrides the project setting. - Review the built-in fallback on the detailed configuration page.
- Confirm enum spelling, type, and path existence.
- Start a new process after editing cached configuration.
- Use debug output to verify the selected path or value when available.
Templates and Initialized Files
- Edit project-owned copies under
.config/custy/, not packaged files under the installedapp/templates/directory. - Confirm commit, tag, and changelog template paths refer to files rather than directories.
- Preserve customized resources before
custy init --force. - If examples are absent, check the selected Init mode; configuration-only or template-only modes intentionally omit them.
- When an explicitly configured version file is missing, correct the path or
set
tool.custy.cli.paths.version_file = "auto". Automatic mode does not require a version file.
Custy Starts in a Project Without app/
The generated configuration uses automatic layout detection:[tool.custy.project]
project_source = "auto"
[tool.custy.cli.paths]
version_file = "auto"
If an older project configuration still contains project_source = "app" or
version_file = "app/__version__.py", those are explicit paths and remain
strict. Change them to auto for Node.js, Docusaurus, generic, mixed, or other
layouts that do not own those paths.
Normal errors are rendered as concise Custy messages. Add --debug before the
command when a traceback is needed for diagnosis.