⚠️ Troubleshooting
Common generator issues and solutions.
Nx Generator Issues
“Cannot find generator”
Cause: Plugin not installed
1
2
3
4
5
6
7
8
| # Check installed plugins
pnpm exec nx list
# Install missing plugin
pnpm add -D @nx/<plugin>
# Verify
pnpm exec nx list @nx/<plugin>
|
“Project already exists”
Cause: Name collision
1
2
3
4
5
| # Check existing projects
pnpm exec nx show projects
# Use different name or remove existing
pnpm exec nx g @nx/workspace:remove old-project
|
“Missing required parameter”
Cause: Required option not provided
1
2
3
4
5
| # Check required options
pnpm exec nx g @nx/js:library --help
# Use interactive mode (prompts for inputs)
pnpm exec nx g @nx/js:library
|
“Cannot resolve dependency”
Cause: Path mapping issues
1
2
3
4
5
6
| # Regenerate path mappings
pnpm exec nx reset
# Clear cache
rm -rf node_modules/.cache
pnpm install
|
Copier Template Issues
“Template not found”
Cause: Wrong path or missing copier.yml
1
2
3
| # Verify template structure
ls -la templates/
cat templates/copier.yml
|
“Hook failed”
Cause: Python hook error
1
2
3
4
5
| # View hook output
copier copy ./templates ./output --verbose
# Check Python syntax
python hooks/post_gen.py
|
“Variable undefined”
Cause: Missing variable in template
1
2
3
4
5
6
7
| {# Use default filter #}
{{ variable | default("fallback") }}
{# Or check if defined #}
{% if variable is defined %}
{{ variable }}
{% endif %}
|
Type Sync Issues
“Types out of sync”
Cause: Manual modifications or schema change
1
2
3
4
5
| # Regenerate all types
just gen-types
# Verify sync
just check-types
|
“Unknown type mapping”
Cause: New database type without mapper
1
2
3
4
5
| # Add to gen_py_types.py
TYPE_MAP = {
# ...existing...
'my_custom_type': 'MyPythonType',
}
|
Generation Pipeline Issues
“CALM validation failed”
Cause: Architecture boundaries violated
1
2
3
4
5
| # Check CALM validation
calm validate
# View violations
calm validate --verbose
|
“SEA™ validation failed”
Cause: DSL syntax or policy violation
1
2
3
4
5
| # Validate DSL
sea validate models/
# View errors
sea validate models/ --verbose
|
Debug Commands
1
2
3
4
5
6
7
8
| # Verbose Nx output
NX_VERBOSE_LOGGING=true pnpm exec nx g ...
# Dry run (no changes)
pnpm exec nx g ... --dry-run
# Show what would be affected
pnpm exec nx show project my-lib --web
|
Getting Help
1
2
3
4
5
6
7
8
| # Generator-specific help
pnpm exec nx g @nx/js:library --help
# General Nx help
pnpm exec nx --help
# Copier help
copier --help
|