Skip to content

troubleshooting.md

Latest commit

 

History

History
204 lines (137 loc) · 4.65 KB

troubleshooting.md

File metadata and controls

204 lines (137 loc) · 4.65 KB
Raw

Troubleshooting

Common issues and solutions for darnit development.

1. Tests Fail with GitHub API Errors

Symptom: Tests fail with gh: not logged in or HTTP 401 Unauthorized errors.

Cause: The GitHub CLI is not authenticated. Many tests use gh api commands.

Solution:

gh auth login
gh auth status  # Verify authentication

If already logged in but still failing, your token may lack required scopes:

gh auth refresh -s read:org,repo

2. uv sync Fails

Symptom: uv sync fails with dependency resolution errors or Python version mismatch.

Cause: Wrong Python version or outdated uv.

Solution:

Check Python version (must be 3.11+):

python3 --version

Update uv:

uv self update

If you have multiple Python versions, specify the version:

uv sync --python 3.12

3. validate_sync.py Fails After Code Changes

Symptom: uv run python scripts/validate_sync.py --verbose reports sync errors after modifying framework behavior.

Cause: The framework-design spec (docs/architecture/framework-design.md) is out of sync with the code. The validator checks that handler names declared in the spec match the registrations in packages/darnit/src/darnit/sieve/builtin_handlers.py.

Solution:

  1. Update the spec first:

    # Edit the spec to reflect your changes
$EDITOR docs/architecture/framework-design.md

  2. Re-run validation:

    uv run python scripts/validate_sync.py --verbose

The validator checks that handler names declared in docs/architecture/framework-design.md match the registrations in packages/darnit/src/darnit/sieve/builtin_handlers.py. Add or update the handler name in the spec to match the registry.

4. Ruff Linting Errors

Symptom: uv run ruff check . reports style or formatting errors.

Cause: Code doesn't match the project's linting rules.

Solution:

Auto-fix most issues:

uv run ruff check --fix .

Format code:

uv run ruff format .

For errors that can't be auto-fixed, read the error message — ruff provides clear explanations and fix suggestions.

5. Import Errors or Missing Packages

Symptom: ModuleNotFoundError: No module named 'darnit' or similar import errors.

Cause: Packages not installed in development mode, or virtual environment not activated.

Solution:

Re-sync all packages:

uv sync

Verify packages are installed:

uv run python -c "import darnit; print(darnit.__file__)"
uv run python -c "import darnit_baseline; print(darnit_baseline.__file__)"

Both should print paths within the packages/ directory (editable installs).

6. Fork Workflow Issues

Upstream remote not configured

Symptom: git fetch upstream fails with fatal: 'upstream' does not appear to be a git repository.

Solution:

git remote add upstream https://github.com/kusari-oss/darnit.git
git fetch upstream

Rebase conflicts

Symptom: git rebase upstream/main shows merge conflicts.

Solution:

# View conflicting files
git status

# Resolve conflicts in each file, then:
git add <resolved-file>
git rebase --continue

# If you want to abort and start over:
git rebase --abort

Push rejected after rebase

Symptom: git push fails with non-fast-forward after rebasing.

Solution:

git push --force-with-lease origin my-branch

Use --force-with-lease (not --force) to safely update your fork's branch.

7. CEL Expression Errors

Symptom: Controls unexpectedly return WARN/INCONCLUSIVE instead of PASS or FAIL.

Cause: CEL expression syntax errors or TOML escaping issues.

Common fixes:

  1. Use ! not not — CEL is C-style, not Python:

    # WRONG
expr = 'not output.any_match'

# CORRECT
expr = '!(output.any_match)'

  2. Use \. not \\. in TOML literal strings for regex dots:

    # WRONG — over-escaped
expr = 'output.stdout.matches("v\\d+\\.\\d+")'

# CORRECT
expr = 'output.stdout.matches("v\d+\.\d+")'

  3. Use && and || not and and or:

    # WRONG
expr = 'output.exit_code == 0 and output.json.enabled'

# CORRECT
expr = 'output.exit_code == 0 && output.json.enabled'

See the CEL Reference for complete syntax documentation.

Getting More Help

If you're stuck: