Error Handling and Troubleshooting

This document covers common errors, environment variables, debugging tips, and OS-specific considerations for agent-sync.

Common Errors

Error	Description	Solution
`configuration file not found`	The agent-sync.yml file could not be found	Ensure you’re in the correct directory or specify the path with `--config`
`invalid configuration format`	The configuration file has syntax errors	Check the YAML syntax for errors
`mixed configuration format`	Both simplified and standard formats were detected	Use either the simplified format or the standard format, not both
`agent not found`	The specified agent is not supported	Check for typos or use `agent-sync list agents` to see supported agents
`file access denied`	Permission issues when reading/writing files	Check file permissions

Environment Variables

agent-sync recognizes the following environment variables:

Variable	Description
`AGENT_SYNC_LOG_FILE`	Log file path (overridden by `--log-file` flag)
`AGENT_SYNC_LOG_LEVEL`	Log level (overridden by `--log-level` flag)

Debugging Tips

Use --dry-run: Preview what would be generated without writing files
Enable debug logging: Use --debug for a shorthand that sets level to debug and enables console output, or use --log-level=debug --verbose explicitly
Check output path formatting: Remember that paths ending with / are treated as directories, while paths without are treated as files
Check file permissions: Ensure you have read permissions for input files and write permissions for output directories
Examine template processing: If you suspect issues with templates, try creating simpler templates first to isolate the problem
Check for conflicting paths: Make sure you’re not writing to the same output file from different tasks

Using Enhanced Dry-Run Mode

The --dry-run flag provides a powerful way to preview and debug your configuration without making actual changes. The enhanced output format offers:

Agent-based organization: Output is grouped by agent, making it easy to see how files will be processed for each target system
Status indicators: Each file is prefixed with one of these status tags:
- [CREATE]: File does not exist and would be created
- [MODIFY]: File exists and its content would be changed
- [UNCHANGED]: File exists and its content would remain the same
File details: For each file, you’ll see:
- Full file path
- File size in human-readable format (B, KB, MB)
Agent summaries: For each agent, a summary is provided showing:
- Number of files that would be created
- Number of files that would be modified
- Number of files that would remain unchanged

Example of using dry-run to debug configuration issues:

# Run in dry-run mode to check configuration
agent-sync apply --dry-run

# If you need more details, combine with debug logging
# Shorthand (debug level + console output)
agent-sync apply --dry-run --debug
# Equivalent explicit form
agent-sync apply --dry-run --log-level debug --verbose

This helps identify issues such as:

Files being created in unexpected locations
Expected modifications not being detected
Unnecessary file duplication
Size discrepancies indicating template processing issues

OS-Specific Considerations

Path Handling

Windows: Both forward slashes (/) and backslashes (\) are supported in paths. Home directory expansion (~) works with the user’s profile directory.
macOS/Linux: Use forward slashes (/) for paths. Home directory expansion (~) works with the user’s home directory.

Default Output Paths

Some default paths differ between operating systems:

Windows:
- Roo user commands (slash commands): %APPDATA%\Code\User\globalStorage\rooveterinaryinc.roo-cline\settings\custom_modes.yaml (for mode tasks)
- Cline user memory: %USERPROFILE%\Documents\Cline\Rules\
macOS:
- Roo user modes (type: mode): ~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/custom_modes.yaml
- Cline user memory: ~/Documents/Cline/Rules/
Linux:
- Roo user modes (type: mode): ~/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/custom_modes.yaml
- Cline user memory: ~/Documents/Cline/Rules/

Note:

Roo “command” tasks generate Roo slash commands to .roo/commands/ (project) or ~/.roo/commands/ (user) by default (directory, per-file).
Roo “mode” tasks aggregate to a single file by default: .roomodes for project scope, and custom_modes.yaml in the platform-specific VS Code globalStorage path for user scope.

Troubleshooting Log Issues

If you’re having issues with logs:

Log file not being created:
- Check if the directory exists and has write permissions
- Use an absolute path to ensure correct location
Missing detailed information:
- Ensure log level is set to debug
- Enable verbose output with --verbose
Too much log information:
- Increase log level to warn or error
- Disable verbose output

For more information about logging configuration, see the Logging Guide.

Previous	Next
Examples and Best Practices

Back to index