> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qwedai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# QWED Legal troubleshooting

> Troubleshoot QWED Legal installation issues, Z3 solver errors, holidays package problems, and legal guard failures.

## Installation issues

### Z3 solver not found

**Error:**

```text theme={null}
ImportError: No module named 'z3'
```

**Solution:**

```bash theme={null}
pip install z3-solver
```

Note: The package is `z3-solver`, not `z3`.

### Holidays package version

**Error:**

```text theme={null}
AttributeError: module 'holidays' has no attribute 'country_holidays'
```

**Solution:**

```bash theme={null}
pip install --upgrade holidays>=0.40
```

***

## DeadlineGuard issues

### Unexpected holiday calculation

**Problem:** Computed deadline differs from expected by a few days.

**Cause:** Different jurisdictions have different holidays.

**Solution:**

```python theme={null}
# Be explicit about jurisdiction
guard = DeadlineGuard(country="US", state="CA")  # California holidays
guard = DeadlineGuard(country="GB")              # UK holidays
guard = DeadlineGuard(country="IN")              # India holidays
```

### "Failed to parse dates" error

**Problem:**

```text theme={null}
Failed to parse dates: Unknown string format
```

**Solution:** Use ISO format or unambiguous dates:

```python theme={null}
# ✅ Good
guard.verify("2026-01-15", "30 days", "2026-02-14")

# ❌ Bad (ambiguous)
guard.verify("01/02/2026", ...)  # Is this Jan 2 or Feb 1?
```

### "UNVERIFIABLE" result on a contract term

**Problem:** `verified=False`, `is_computable=False`, and the message starts with `⚠️ UNVERIFIABLE`.

**Cause:** The `term` argument did not contain both a numeric quantity and a recognized time unit. `DeadlineGuard` fails closed on ambiguous legal language ("reasonable period", "promptly", "as soon as practicable", "forthwith") instead of inventing a deadline.

**Solution:** Pass an explicit term with a number and a unit. Recognized units are `day(s)`, `business day(s)`, `calendar day(s)`, `week(s)`, `month(s)`, and `year(s)`.

```python theme={null}
# ✅ Good — explicit quantity and unit
guard.verify("2026-01-01", "30 days", "2026-01-31")
guard.verify("2026-01-01", "10 business days", "2026-01-15")
guard.verify("2026-01-01", "2 weeks", "2026-01-15")

# ❌ Fails closed — no numeric quantity
guard.verify("2026-01-01", "within a reasonable period", "2026-01-31")

# ❌ Fails closed — no recognized time unit
guard.verify("2026-01-01", "30", "2026-01-31")
guard.verify("2026-01-01", "15 intervals", "2026-01-16")
```

If your contract uses subjective language, route the clause to a human reviewer rather than overriding the guard. Always check `is_computable` before consuming `computed_deadline` or `difference_days`.

***

## LiabilityGuard issues

### Float precision errors

**Problem:** Small differences in large calculations.

**Cause:** Floating-point precision.

**Solution:** LiabilityGuard uses `Decimal` internally. The default tolerance is 0.01%. Adjust if needed:

```python theme={null}
guard = LiabilityGuard(tolerance_percent=0.001)  # Stricter
guard = LiabilityGuard(tolerance_percent=0.1)    # More lenient
```

***

## ClauseGuard issues

### No conflicts detected (false negative)

**Problem:** You expect a conflict but ClauseGuard doesn't find it.

**Cause:** ClauseGuard uses heuristic pattern matching, not full NLP.

**Current Limitations:**

* Only detects termination-related conflicts
* Limited to English text
* Requires specific keyword patterns

**Workaround:** For complex contracts, extract key terms manually:

```python theme={null}
clauses = [
    "Termination allowed after 30 days notice",  # Clear pattern
    "Minimum term 90 days",                       # Clear pattern
]
```

***

## CitationGuard issues

### Valid citation marked invalid

**Problem:** A real citation is flagged as invalid.

**Cause:** The reporter isn't in our list.

**Solution:** Check if the reporter is a valid Bluebook abbreviation. If it's a less common reporter, it may not be in our list. File an issue to add it: [https://github.com/QWED-AI/qwed-legal/issues](https://github.com/QWED-AI/qwed-legal/issues)

### Statute citation format

**Problem:** `42 USC 1983` doesn't validate.

**Solution:** Use proper formatting with section symbol:

```python theme={null}
# ✅ Correct
guard.check_statute_citation("42 U.S.C. § 1983")

# ❌ Missing section symbol
guard.check_statute_citation("42 USC 1983")
```

***

## StatuteOfLimitationsGuard issues

### `UNVERIFIABLE` result for a jurisdiction or claim type

**Problem:** `guard.verify(...)` returns `verified=False` with a message that starts with `⚠️ UNVERIFIABLE`, and `limitation_period_years` is `None`.

**Cause:** As of the fail-closed update, `StatuteOfLimitationsGuard` only computes a result when both the jurisdiction and the claim type match the rule table exactly. There is no longer a substring match (`"CALIF"` → `"CALIFORNIA"`) or a default fallback (3 years for unknown claim types).

**Solution:** Inspect the new flags on `StatuteResult` to see which lookup failed, then pass a supported value:

```python theme={null}
result = guard.verify(
    claim_type="breach_of_contract",
    jurisdiction="Calif",
    incident_date="2023-01-15",
    filing_date="2026-06-01",
)

if not result.jurisdiction_matched:
    # Use the full supported name, e.g. "California"
    ...
elif not result.claim_type_matched:
    # Use one of the supported claim types, e.g. "breach_of_contract"
    ...
```

The full list of supported jurisdictions and claim types is included in the `result.message` and documented in [Guards — StatuteOfLimitationsGuard](/legal/guards#6-statuteoflimitationsguard).

### Treating unverifiable as "in period"

**Problem:** Downstream code passes when `result.verified` is `False` because it expects a numeric limitation period.

**Cause:** `StatuteResult.limitation_period_years` and `expiration_date` are now `Optional` and are `None` for unverifiable inputs. Code that does `if result.days_remaining > 0` will raise on `None`.

**Solution:** Branch on `verified` and the new `*_matched` flags before reading numeric fields:

```python theme={null}
if not result.verified and not (
    result.jurisdiction_matched and result.claim_type_matched
):
    raise ValueError(result.message)  # Surface to the user — do not pass.
```

***

## General issues

### Import errors

**Problem:**

```text theme={null}
ImportError: cannot import name 'LegalGuard' from 'qwed_legal'
```

**Solution:**

```bash theme={null}
pip install --upgrade qwed-legal
```

### Version mismatch with MCP

**Problem:** MCP tools don't show legal verification options.

**Solution:** Reinstall qwed-mcp after installing qwed-legal:

```bash theme={null}
pip install qwed-legal
pip install --upgrade qwed-mcp
```

***

## Still stuck?

* [GitHub Issues](https://github.com/QWED-AI/qwed-legal/issues)
* [Discord Community](https://discord.gg/qwed)
* Email: [support@qwedai.com](mailto:support@qwedai.com)